About object and component Help
About VCL Help

See also

The VCL online Help is the main source of information on C++Builder objects, components, global routines, types, and variables. The individual entries for objects, components, routines, types, and variables include the unit (header file) in which each is declared. These header files are located in the CBuilder3\Include directory.

Objects

A C++Builder object consists of methods, and in many cases, properties, and events. Properties represent the data contained in the object. Methods are the actions the object can perform. Events are conditions the object can react to. All objects descend from the ancestor object TObject.

Components

Components are visual objects that you can manipulate at design time. All components descend from TComponent.

Routines

Global routines are the procedures and functions from the runtime library and from the Visual Component Library (VCL). These routines are not part of a class, but can be called either directly or from within class methods.

Types

The types described in the Help are used as return types and parameter types for object methods, properties and events, and for global routines. In most cases types are documented in the entry for the method, property, event or global routine in which they are used.

Variables

The variables defined in the Help are declared in the runtime library and in the VCL. Some of these variables are instantiations of objects. Examples are the Application and ComServer variables.

The Help on all of these topics can be accessed either by using the F1 key from the IDE or by using the Contents, Index, or Find from Help.


How to find Help using F1

See also

To display Help on a property or event, press the F1 key while the cursor is that property or event as it appears in a cell in the Object Inspector.

To bring up Help on objects, components, methods, global routines, variables, types, or general topics, as well as on properties and events, type the word in your edit window and press F1 while the cursor in on that word.


How to find Help by selecting Contents

See also

The Contents tab in Help provides information in 4 groups:

A hierarchical list of objects and components

An alphabetical list of objects and components

A categorical list of routines

An alphabetical list of routines

An alphabetical list of types, variables, and constants

The hierarchical listing is divided into six main categories of objects and components, which are:

TObject - objects derived from TObject that are not descendants of TPersistent

TPersistent - persistent objects that are not components

TComponent - components that are not controls

TControl - TControl

TGraphicControl - controls that do not have a Window handle

TWinControl - window controls

These six categories correspond to the C++Builder object hierarchy. Each is further sub-divided into functional groups of objects within the hierarchy structure. For example, components has a sub-group for Dialogs, and window controls has a sub-group for Edit controls. Thus, when you are looking for information about which specific object to use and want to quickly compare functionality, you may prefer to use the hierarchical list to navigate Help on objects.


How to find Help by selecting Index or Find

See also

To find Help on an object, component, method, property, event, routine, type, variable, or topic, type the word in the edit window  and press Enter or click on the topic found.

To access Help from Find, type the word in the edit window, select matching words to narrow your search, and click on the topic you want to display.


How to use examples in Help

See also

The VCL Help includes a number of examples for methods, properties, and events. Code examples for the methods, properties, and events are accessible by clicking the example link.


How to program with a component

See also

1.	Select a component from  Component palette and add it to a form.

2.	Set property values of the component using the Object Inspector.

3.	Respond to events that might occur to the component at runtime. To respond to an event, you write code within an event handler. Your code modifies property values and calls methods.


TAbstractSocket

Hierarchy	Properties	Methods	See also

TAbstractSocket is the abstract base class for all socket components.

Unit

scktcomp

Description

TAbstractSocket introduces properties and methods to enable an application to work with Windows sockets. A Windows socket encapsulates a set of communication protocols to allow the application to connect to other machines for reading or writing information. Windows sockets provide connections based on the TCP/IP protocol. They also allow connections that use the Xerox Network System (XNS), Digital’s DECnet protocol, or Novell’s IPX/SPX family. Sockets allow an application to form connections to other machines without being concerned with the details of the actual networking software.

The properties of TAbstractSocket describe the IP address of the socket and service it provides or seeks. Not all descendents of TAbstractSocket use all of these properties. For example, server sockets do not surface the IP address because it is read implicitly from the system running the application.

Do not create instances of TAbstractSocket. Use a descendant of TAbstractSocket to add the ability to communicate with other machines to an application. To create a socket that initiates the connection with another machine, use TClientSocket. To create a socket that responds to requests for connections from other machines, use TServerSocket.


TAbstractSocket properties

TAbstractSocket	Alphabetically	Legend

In TAbstractSocket

Active

Address

Host

Port

Service

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TAbstractSocket properties

TAbstractSocket	By object	Legend

Active

Address

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Host

Name

Owner

Port

Service

Tag

VCLComObject


TAbstractSocket::Active

TAbstractSocket	See also	Example

Indicates whether the socket connection is open and available for communication with other machines.

__property bool Active = {read=FActive, write=SetActive, nodefault};

Description

Before attempting to use or change the socket connection, read Active to determine whether the connection is open and ready. For client sockets, setting Active opens or shuts down a socket connection to another machine. For server sockets, setting Active opens or shuts down a listening connection that makes the socket available for client requests.

At design time, set Active to true to make the socket open a connection when the application starts running. At runtime, use the Open or Close method to open or close the connection.


TAbstractSocket::Address

TAbstractSocket	See also

Specifies the IP address of the server system.

__property System::AnsiString Address = {read=FAddress, write=SetAddress};

Description

Address is a string of four numeric (byte) values in the standard internet dot notation, such as

123.197.1.2

For client sockets, set Address to the IP address of the server to which the socket should connect. When the connection is opened, the value of Address is bound to the connection.

If the socket specifies the Host property, the address for the connection is taken from the IP address associated with Host, rather than the value of Address. Specifying the server system by giving the IP address is faster, because the socket doesn’t need to search for the IP address associated with the host name before it can locate the server system.

A single system may support more than one IP address.

Note:	Trying to change Address when the connection is open will raise an ESocketError exception.


TAbstractSocket::Host

TAbstractSocket	See also

Specifies an alias for the IP address of the server system.

__property System::AnsiString Host = {read=FHost, write=SetHost};

Description

Host is a string containing the domain name and service of a particular system, such as

http://www.wSite.Com

For client sockets, set Host to the system with which the client socket should form a connection. When the socket opens a connection, it looks up the IP address for the server socket using the value of Host.

Some servers change the system or IP address that is associated with a particular host name. Using a host name allows the client socket to find the abstract site represented by the host name, even when it has moved to a new IP address.

If Host is set, it takes precedence over the Address property when looking up the address of the server.

Note:	Trying to change Host when the connection is open will raise an ESocketError exception.


TAbstractSocket::Port

TAbstractSocket	See also

Specifies the ID number that identifies the server socket connection.

__property int Port = {read=FPort, write=SetPort, nodefault};

Description

Port numbers allow a single system, identified by the Host or Address property, to host multiple connections simultaneously. Many values of Port are associated by convention with a particular service such as ftp or http.

For server sockets, Port is the ID of the connection on which the server socket listens for client requests. Server sockets generally set Port to a predefined value which clients can use to initiate connections.

For client sockets, Port is the ID of the desired server connection. The value of Port is usually associated with the service the client wishes to use on the server application.

Note:	Trying to change Port when the connection is open will raise an ESocketError exception.


TAbstractSocket::Service

TAbstractSocket	See also

Specifies the name of the service for which the socket connection is used.

__property System::AnsiString Service = {read=FService, write=SetService};

Description

Use Service to identify the use of the connection. Windows provides a number of standard service names such as ftp, http, finger, and time. Servers can specify additional services and their associated ports in a SERVICES file. For more information, see the Microsoft documentation for Windows sockets.

Certain port numbers are reserved for specific values of service. Thus, Service provides a more meaningful way to specify the server Port to use for the socket connection. For server sockets, using Service rather than Port ensures that the server will listen for TCP/IP requests on the appropriate port.

Note:	Trying to change Service when the connection is open will raise an ESocketError exception.


TAbstractSocket methods

TAbstractSocket	Alphabetically	Legend

In TAbstractSocket

~TAbstractSocket

Close

DoActivate

Error

Event

InitSocket

Loaded

Open

SetActive

SetAddress

SetHost

SetPort

SetService

TAbstractSocket

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TAbstractSocket methods

TAbstractSocket	By object	Legend

~TAbstractSocket

AfterConstruction

Assign

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

DefaultHandler

DestroyComponents

Destroying

Dispatch

DoActivate

Error

Event

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InitSocket

InsertComponent

InstanceSize

Loaded

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

SafeCallException

SetActive

SetAddress

SetHost

SetPort

SetService

TAbstractSocket


TAbstractSocket::Close

TAbstractSocket	See also

Shuts down the socket connection.

void __fastcall Close(void);

Description

Call Close to shut down the socket connection. Close sets the Active property to false.

For client sockets, Close terminates the connection to the server. For server sockets, Close shuts down the connection so that the server socket is no longer listening for client requests.


TAbstractSocket::DoActivate

TAbstractSocket	See also

Provides the prototype of a method to open or close the socket connection.

virtual void __fastcall DoActivate(bool Value) = 0;

Description

Descendants of TAbstractSocket override DoActivate to provide a method that initiates or terminates the socket connection. The steps that need to be taken to open or close a connection depend on whether the socket is a client socket or a server socket.


TAbstractSocket::Error

TAbstractSocket	See also

Provides the prototype of a method that responds to error conditions.

enum TErrorEvent { eeGeneral, eeSend, eeReceive, eeConnect, eeDisconnect, eeAccept };

virtual void __fastcall Error(TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode) = 0;

Description

Descendants of TAbstractSocket must override the pure virtual Error method to provide a response when socket errors occur. Applications cannot call Error. The Windows socket object that encounters the error condition calls Error automatically.

The Socket parameter indicates the Windows socket object which encounters the error condition.

The ErrorEvent parameter indicates what the socket was trying to do when the error occurred. It has one of the following values:

Value	Meaning

eeGeneral	The socket received an error message that does not fit into any of the following categories.

eeSend	An error occurred when trying to write to the socket connection.

eeReceive	An error occurred when trying to read from the socket connection.

eeConnect	For client sockets, this indicates that the client socket can’t locate the server, or that a problem on the server prevents the opening of a connection. For server sockets, this indicates that a client connection request that has already been accepted could not be completed.

eeDisconnect	An error occurred when trying to close a connection.

eeAccept	For server sockets only, this indicates that a problem occurred when trying to accept a client connection request.

The ErrorCode parameter is the error code received by the Windows socket object. Setting this value to 0 in the Error method prevents the socket from raising an exception. For information on possible error codes, see the Microsoft documentation on Windows sockets.


TAbstractSocket::Event

TAbstractSocket	See also

Provides the prototype of a method that responds when specific socket events occur.

enum TSocketEvent { seLookup, seConnecting, seConnect, seDisconnect, seListen, seAccept, seWrite, seRead };

virtual void __fastcall Event(TCustomWinSocket* Socket, TSocketEvent SocketEvent) = 0;

Description

Descendants of TAbstractSocket must override the pure virtual Event method to provide a response to calls that arise during the normal functioning of the socket . Applications cannot call Event. The Windows socket object calls Event at appropriate times.

The Socket parameter indicates the Windows socket object that calls Event to indicate when specific events occur.

The SocketEvent parameter indicates the event that occured. It has one of the following values:

Value	Meaning

seLookup	(client sockets only) The Windows socket object is about to locate the server socket. Changing the propreties of the client socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will affect the attempted connection.

seConnecting	(client sockets only) The server socket has been located but the connection isn’t completed. This is the first opportunity to obtain the actual server port and IP address used for the connection, which may differ from those of the listening socket contacted initially.

seConnect	The socket connection has just been established. This is the point when a socket starts reading or writing over the connection.

seListen	(server sockets only) The Windows socket object has been initialized and is about to open a listening connection. Changing the propreties of the server socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will the listening connection.

seAccept	(server sockets only) A client connection request has just been accepted. This is the first opportunity to obtain the port and IP address of the individual client connection.

seWrite	The socket is ready for information to be written.

seRead	The socket is receiving information from a socket on the other end of the connection.


TAbstractSocket::InitSocket

TAbstractSocket	See also

Tells a Windows socket object to call the Error and Event methods.

void __fastcall InitSocket(TCustomWinSocket* Socket);

Description

Applications cannot call this protected method. InitSocket is called automatically by the socket’s constructor, immediately after the Windows socket object is created. It allows the socket component to respond to events on the Windows socket object by assigning an OnErrorEvent handler that calls Error and an OnSocketEvent handler that calls Event.

The Socket parameter specifies the Windows socket object that passes events on to the socket component.


TAbstractSocket::Loaded

TAbstractSocket	See also

Opens or closes the socket connection when the socket is loaded from a file, depending on the saved value of the Active property.

virtual void __fastcall Loaded(void);

Description

Applications cannot call this protected method. Loaded is called automatically after the socket component has been loaded from a stream. Loaded overrides the default method to implement the value of the Active property that was saved with the socket component.


TAbstractSocket::Open

TAbstractSocket	See also

Opens the socket connection.

void __fastcall Open(void);

Description

Call Open to initiate the socket connection. Open sets the Active property to true.

For client sockets, Open locates and connects to a server. For server sockets, Open opens the socket connection in a listening mode, but does not complete the connection to a client socket.


TAbstractSocket::SetActive

TAbstractSocket	See also

Sets the Active property.

void __fastcall SetActive(bool Value);

Description

SetActive is the protected implementation of the Active property. SetActive calls the DoActivate method to open or close the socket connection.


TAbstractSocket::SetAddress

TAbstractSocket	See also

Sets the Address property.

void __fastcall SetAddress(System::AnsiString Value);

Description

SetAddress is the protected implementation of the Address property. SetAddress throws an ESocketError exception if an attempt is made to set the Address property when the socket connection is open.


TAbstractSocket::SetHost

TAbstractSocket	See also

Sets the Host property.

void __fastcall SetHost(System::AnsiString Value);

Description

SetHost is the protected implementation of the Host property. SetHost throws an ESocketError exception if an attempt is made to set the Host property when the socket connection is open.


TAbstractSocket::SetPort

TAbstractSocket	See also

Sets the Port property.

void __fastcall SetPort(int Value);

Description

SetPort is the protected implementation of the Port property. SetPort throws an ESocketError exception if an attempt is made to set the Port property when the socket connection is open.


TAbstractSocket::SetService

TAbstractSocket	See also

Sets the Service property.

void __fastcall SetService(System::AnsiString Value);

Description

SetService is the protected implementation of the Service property. SetService throws an ESocketError exception if an attempt is made to set the Service property when the socket connection is open.


TAbstractSocket::TAbstractSocket

TAbstractSocket

Creates a new TAbstractSocket object.

__fastcall virtual TAbstractSocket(Classes::TComponent* AOwner) : Classes::TComponent(AOwner) { }

Description

Do not call the TAbstractSocket constructor. Instead, use the new keyword to call the constructor for the appropriate descendent of TAbstractSocket. Sockets placed in forms or data modules at design time are created automatically.


TAbstractSocket::~TAbstractSocket

TAbstractSocket

Frees the memory associated with the TAbstractSocket object.

__fastcall virtual ~TAbstractSocket(void) { }

Description

Do not call ~TAbstractSocket directly. Instead, use the delete keyword on the object, which causes ~TAbstractSocket to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TActiveForm

Hierarchy	Properties	Methods	Events	See also

TActiveForm is the base class for a VCL Form exposed as an ActiveX control. TActiveForm represents a form that is created via the ATL (Active Template Library) and used as an ActiveX control in ActiveX host applications.

Unit

atlvcl

Description

A TActiveForm object is used to create a form ActiveX control that can be displayed and run from within Web browsers.


TActiveForm properties

TActiveForm	Alphabetically	Legend

Derived from TCustomActiveForm

AxBorderStyle

Derived from TCustomForm

Active

ActiveControl

ActiveOleControl

Canvas

ClientRect

Designer

DropTarget

KeyPreview

Menu

ModalResult

OleFormObject

Parent

PixelsPerInch

PrintScale

Scaled

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TActiveForm properties

TActiveForm	By object	Legend

Active

ActiveControl

ActiveOleControl

Align

AutoScroll

AxBorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

Handle

Height

HelpContext

Hint

HorzScrollBar

KeyPreview

Left

Menu

ModalResult

Name

OleFormObject

Owner

Parent

ParentWindow

PixelsPerInch

PopupMenu

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

VertScrollBar

Visible

Width

WindowProc

WindowState


TActiveForm events

TActiveForm	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnCreate

OnDeactivate

OnDestroy

OnPaint

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TActiveForm events

TActiveForm	By object	Legend

OnActivate

OnClick

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint


TActiveForm methods

TActiveForm	Alphabetically

In TActiveForm

~TActiveForm

TActiveForm

Derived from TCustomActiveForm

CreateParams

WantChildKey

Derived from TCustomForm

Close

CloseQuery

DefocusControl

FocusControl

GetFormImage

Hide

Print

Release

SendCancelMode

SetFocus

SetFocusedControl

Show

ShowModal

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TActiveForm methods

TActiveForm	By object

~TActiveForm

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

CreateParams

DefaultHandler

DefocusControl

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Print

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetFocus

SetFocusedControl

SetTextBuf

Show

ShowModal

TActiveForm

Update

UpdateControlState

WantChildKey


TActiveForm::TActiveForm

TActiveForm	See also

Creates an instance of TActiveForm.

__fastcall virtual TActiveForm(HWND ParentWindow): Forms::TCustomActiveForm(ParentWindow) {}

__fastcall virtual TActiveForm(TComponent* AOwner): Forms::TCustomActiveForm(AOwner) {}

Description

To create an active form at runtime, call TActiveForm indirectly, using the new keyword.

Pass a single Component as a parameter to provide the TActiveForm object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the active form control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TActiveForm calls and then overrides the parent object’s constructor to initialize the AxBorderStyle property.


TActiveForm::~TActiveForm

TActiveForm

~TActiveForm frees the memory associated with the TActiveForm object.

__fastcall ~TActiveForm(void);

Description

Do not call ~TActiveForm directly. Instead, use the delete keyword on the object, which causes ~TActiveForm to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm


TAdapterNotifier

Hierarchy	Properties	Methods	See also

TAdapterNotifier provides the binding between a C++Builder type object and comparable OLE type object.

Unit

axctrls

Description

Descendents of TCustomAdapter use TAdapterNotifier to bind C++Builder objects with corresponding OLE objects. For example, TFontAdapter uses TAdapterNotifier to bind a TFont object and an OLE font object.


TAdapterNotifier properties

TAdapterNotifier	Alphabetically	Legend

Derived from TInterfacedObject

RefCount


TAdapterNotifier properties

TAdapterNotifier	By object	Legend

RefCount


TAdapterNotifier methods

TAdapterNotifier	Alphabetically

In TAdapterNotifier

~TAdapterNotifier

TAdapterNotifier

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TAdapterNotifier methods

TAdapterNotifier	By object

~TAdapterNotifier

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TAdapterNotifier


TAdapterNotifier::TAdapterNotifier

TAdapterNotifier	See also

Creates an instance of a TAdapterNotifier object.

__fastcall TAdapterNotifier(TCustomAdapter* Adapter);

Description

You would normally never create an object of this class.  This object is created by and bound to a descendent of TCustomAdapter.


TAdapterNotifier::~TAdapterNotifier

TAdapterNotifier

~TAdapterNotifier frees the memory associated with the TAdapterNotifier object.

__fastcall virtual ~TAdapterNotifier(void) { }

Description

Do not call ~TAdapterNotifier directly. Instead, use the delete keyword on the object, which causes ~TAdapterNotifier to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject


TActiveFormControl

Hierarchy	Properties	Methods	See also

A COM object which provides the interfaces necessary to support an ActiveX control.

Unit

axctrls

Description

TActiveFormControl acts as the bridge between a C++Builder form and the ActiveX control API.


TActiveFormControl properties

TActiveFormControl	Alphabetically	Legend

Derived from TActiveXControl

Control

Derived from TComObject

Controller

Factory

RefCount


TActiveFormControl properties

TActiveFormControl	By object	Legend

Controller

Control

Factory

RefCount


TActiveFormControl methods

TActiveFormControl	Alphabetically

In TActiveFormControl

~TActiveFormControl

FreeOnRelease

InitializeControl

Invoke

ObjQueryInterface

TActiveFormControl

Derived from TActiveXControl

Initialize

PropChanged

PropRequestEdit

Derived from TComObject

ObjAddRef

ObjRelease

SafeCallException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TActiveFormControl methods

TActiveFormControl	By object

~TActiveFormControl

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

Initialize

InitializeControl

InitInstance

InstanceSize

Invoke

MethodAddress

MethodName

NewInstance

ObjAddRef

ObjQueryInterface

ObjRelease

PropChanged

PropRequestEdit

SafeCallException

TActiveFormControl


TActiveFormControl::FreeOnRelease

TActiveFormControl

Supports the IVCLComObject interface.

Description

FreeOnRelease exists solely to support the IVCLComObject and is not implemented.


TActiveFormControl::InitializeControl

TActiveFormControl

InitializeControl creates the TActiveForm instance and establishes a link between itself and the TActiveForm referenced by the control properties.

Description

InitializeControl also instructs the TActiveForm object to perform any of its own initialization.


TActiveFormControl::Invoke

TActiveFormControl

Invoke implements the OLE Automation IDispatch Invoke function.

Description

Call Invoke to access the property or method specified by the DispID parameter. The Flags parameter indicates whether the DispID refers to method (DISPATCH_METHOD), a property value that is being read (DISPATCH_PROPERTYGET), or a property value that is being set (DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF).  The Params and ExcepInfo parameters hold parameters and exception information, respectively, and depend on the property or method identified by the DispID parameter.

Invoke returns S_OK if it is successful.  Otherwise, it returns an error code defined by the IDispatch interface.


TActiveFormControl::ObjQueryInterface

TActiveFormControl	See also

The ObjQueryInterface method takes an interface ID (the IID parameter) and returns the requested COM interface on the object.

Description

The ObjQueryInterface method forwards the call first to the associated TActiveForm object if it supports the requested interface, otherwise it queries its own interface.


TActiveFormControl::TActiveFormControl

TActiveFormControl

TActiveFormControl creates a new TActiveFormControl object.


TActiveFormControl::~TActiveFormControl

TActiveFormControl

~TActiveFormControl frees the memory associated with the TActiveFormControl object. Do not call ~TActiveFormControl directly. Instead, use the delete keyword on the object, which causes ~TActiveFormControl to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TComObject

TTypedComObject

TAutoObject

TActiveXControl


TActiveFormFactory

Hierarchy	Properties	Methods	See also

The ActiveFormFactory object is the class factory for TActiveForm.

Unit

axctrls

Description

The ActiveFormFactory object is the class factory resposible for creating instances of the TActiveFormControl object and therefore TActiveForm object.


TActiveFormFactory properties

TActiveFormFactory	Alphabetically	Legend

Derived from TActiveXControlFactory

EventIID

EventTypeInfo

MiscStatus

ToolboxBitmapID

WinControlClass

Derived from TAutoObjectFactory

DispIntfEntry

DispTypeInfo

Derived from TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TActiveFormFactory properties

TActiveFormFactory	By object	Legend

ClassID

ClassName

ComClass

ComServer

Description

DispIntfEntry

DispTypeInfo

ErrorIID

EventIID

EventTypeInfo

Instancing

LicString

MiscStatus

ProgID

SupportsLicensing

ToolboxBitmapID

WinControlClass


TActiveFormFactory methods

TActiveFormFactory	Alphabetically

In TActiveFormFactory

~TActiveFormFactory

GetIntfEntry

TActiveFormFactory

Derived from TActiveXControlFactory

AddVerb

UpdateRegistry

Derived from TTypedComObjectFactory

ClassInfo

GetInterfaceTypeInfo

Derived from TComObjectFactory

CreateComObject

RegisterClassObject

Derived from TObject

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TActiveFormFactory methods

TActiveFormFactory	By object

~TActiveFormFactory

AddVerb

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComObject

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetInterfaceTypeInfo

GetIntfEntry

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

SafeCallException

TActiveFormFactory

UpdateRegistry


TActiveFormFactory::GetIntfEntry

TActiveFormFactory	See also

The GetIntfEntry method retrieves a pointer to the dispatch interface.

Description

The GetIntfEntry method retrieves a pointer to the dispatch interface from the associated TActiveForm object.


TActiveFormFactory::TActiveFormFactory

TActiveFormFactory

TActiveFormFactory creates a new TActiveFormFactory object.


TActiveFormFactory::~TActiveFormFactory

TActiveFormFactory

~TActiveFormFactory frees the memory associated with the TActiveFormFactory object. Do not call ~TActiveFormFactory directly. Instead, use the delete keyword on the object, which causes ~TActiveFormFactory to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TComObjectFactory

TTypedComObjectFactory

TAutoObjectFactory

TActiveXControlFactory


TAggregatedObject

Hierarchy	Properties	Methods	See also

TAggregatedObject provides the functionality for an inner object of an aggregate by implementing the IUnknown methods to delegate to the controlling IUnknown.

Unit

axctrls

Description

An aggregated COM object is an object composed of several COM objects. Each object implements its own behavior and interfaces, but all of the objects share the same reference count, which is that of the controller object. In the container pattern, the controller is the container object.

TAggregatedObject does not itself support any interfaces. However, as is typical of an aggregate, it does implement the methods of IUnknown, which are used by the objects it contains. TAggregatedObject, therefore, serves as a base for classes that implement interfaces for creating objects that are part of an aggregate.

In the C++Builder class hierarchy, TAggregatedObject is used as a base for classes that create contained objects and connecting objects. Using TAggregatedObject ensures that calls to the IUknown methods delegate to the controlling IUnknown of the aggregate.

The controlling IUknown is specified in the constructor for TAggregatedObject and is indicated by the Controller property.

For more information about aggregation, controlling objects, and interfaces, see the Inside OLE, second edition, by Kraig Brockschmidt, the Microsoft Web site, or the Windows SDK Help.


TAggregatedObject properties

TAggregatedObject	Alphabetically	Legend

In TAggregatedObject

Controller


TAggregatedObject properties

TAggregatedObject	By object	Legend

Controller


TAggregatedObject::Controller

TAggregatedObject	See also

Provides access to the IUnknown of the aggregate.

__property _di_IUnknown Controller = {read=GetController};

Description

Controller is the IUnknown interface reference of the aggregate. TAggregatedObject is used as part of an aggregate which has a single controlling IUnknown. The IUnknown methods that are implemented in aggregated objects are delegated to the Controller.

When the aggregated object is created, its constructor is passed a controlling IUnknown. Controller is initialized to this IUnknown in the constructor.


TAggregatedObject methods

TAggregatedObject	Alphabetically

In TAggregatedObject

~TAggregatedObject

TAggregatedObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TAggregatedObject methods

TAggregatedObject	By object

~TAggregatedObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TAggregatedObject


TAggregatedObject::TAggregatedObject

TAggregatedObject	See also

Instantiates an aggregated object.

__fastcall TAggregatedObject(_di_IUnknown Controller);

Description

Call TAggregatedObject to instantiate an aggregated object at runtime.

TAggregatedObject allocates memory for an aggregated object, and sets the Controller property to the Controller parameter passed to it. The Controller is the controlling IUnknown of the aggregate. All other interfaces implmented in the aggregate will delegate the IUnknown method calls to this Controller.


TAggregatedObject::~TAggregatedObject

TAggregatedObject	See also

~TAggregatedObject frees the memory associated with the TAggregatedObject object.

__fastcall virtual ~TAggregatedObject(void) { }

Description

Do not call ~TAggregatedObject directly. Instead, use the delete keyword on the object, which causes ~TAggregatedObject to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject


TWebActionItem

Hierarchy	Properties	Methods	Events	See also

TWebActionItem allows a Web server application to create and send responses to HTTP request messages.

Unit

http

Description

Use TWebActionItem to assemble the response to a particular type of HTTP request message in a Web server application. Each action item is specific to a particular URI path and HTTP request method.

The TWebDispatcher object chooses an appropriate action item to handle an HTTP request message by matching the path portion of the URI requested by the Web client with the PathInfo property in the TWebActionItem object, and matching the method requested by the Web client with the method type the action item knows how to handle.

An action item handles an HTTP request message in its OnAction event handler. The OnAction event handler should read the request message and assemble a response by setting the properties of a TWebResponse object. It can tell the TWebResponse object to send the response message back to the Web client, or allow the TWebApplication object to send the message after other action items have had a chance to add to the response.


TWebActionItem properties

TWebActionItem	Alphabetically	Legend

In TWebActionItem

Default

DisplayName

Enabled

MethodType

Name

PathInfo

Derived from TCollectionItem

Collection

ID

Index


TWebActionItem properties

TWebActionItem	By object	Legend

Collection

Default

DisplayName

Enabled

ID

Index

MethodType

Name

PathInfo


TWebActionItem::Default

TWebActionItem	See also

Indicates whether the action item should handle any request that is not handled by another available action item.

__property bool Default = {read=FDefault, write=SetDefault, default=0};

Description

Set Default to true to make this action item the default action in the list of action items maintained by the TWebDispatcher object. TWebDispatcher attempts to match HTTP request messages to action items by matching the MethodType and PathInfo of the target URI. If no match can be found, the TWebDispatcher invokes the OnAction event handler of the default action item, regardless of its MethodType or PathInfo properties.

When an action item is chosen as the default action item, the value of its Enabled property is ignored. Thus, if an action item sets Enabled to false and Default to true, TWebDispatcher will first look for a match with any other action item, even if the PathInfo and MethodType of the default action item match the request perfectly. Then, only after all other action items have been rejected, TWebDispatcher selects the default action item. If the default action item is enabled, it may be selected before all other action items have been considered because the MethodType and PathInfo match the request.

The OnAction event handler of the default action item must be prepared to generate a response to any HTTP request, for any MethodType and PathInfo. This may consist of simply setting a response status code of 404 (the URI could not be matched) or 405 (the requested method is not supported).

Setting Default to true sets the Default property of the previous default action item to false.


TWebActionItem::DisplayName

TWebActionItem	See also

Names an individual action item within a collection of action items.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

Use DisplayName to specify a particular action item in the list of action items maintained by the TCustomWebDispatcher object. When setting the DisplayName property, the new value must not match the DisplayName of any other action item in the list maintained by the TCustomWebDispatcher object. Trying to set the DisplayName to a DisplayName that is already in use throws an exception.


TWebActionItem::Enabled

TWebActionItem	See also

Indicates whether the action item can respond to HTTP request messages that match its MethodType and PathInfo properties.

__property bool Enabled = {read=FEnabled, write=SetEnabled, default=1};

Description

Set Enabled to false to disable an action item. TWebDispatcher will ignore disabled action items when it looks for an action item to handle a request.

When an action item is chosen as the default action item, the value of its Enabled property is ignored. Thus, if an action item sets Enabled to false and Default to true, TWebDispatcher will first look for a match with any other action item, even if the PathInfo and MethodType of the default action item match the request perfectly. Then, only after all other action items have been rejected, the TWebDispatcher selects the default action item. If the default action item is enabled, it may be selected before all other action items have been considered because the MethodType and PathInfo match the request.


TWebActionItem::MethodType

TWebActionItem	See also

Specifies the type of HTTP request methods the action item knows how to service.

enum TMethodType { mtAny, mtGet, mtPut, mtPost, mtHead };

__property TMethodType MethodType = {read=FMethodType, write=SetMethodType, default=0};

Description

Set MethodType to indicate the types of requests that are serviced by the OnAction event handler. TWebDispatcher chooses an action item to handle an HTTP request message when the MethodType of the action item matches the MethodType of the request message. (The PathInfo properties must also match).

MethodType can take one of the following values:

Value	Meaning

mtGet	The response should provide the information identified by the URL property of the request.

mtHead	The response should specify the header properties as if servicing an mtGet request, but omit the Content of the response.

mtPost	The Content of the request should be posted, usually to the target URI but not necessarily.

mtPut	The Content of the request should be used to replace the resource indicated by the URL property of the request.

mtAny	The action item handles any request method type, including mtGet, mtHead, mtPost and mtPut.

Add action items with MethodType set to mtAny to the end of the Actions list of the TWebDispatcher object. That way, any action item that exactly matches a request with a MethodType of mtGet, mtHead, mtPost, or mtPut will be chosen before the mtAny value is matched to the request.


TWebActionItem::Name

TWebActionItem	See also

Identifies an individual action item when it is referenced from other objects.

__property System::AnsiString Name = {read=GetDisplayName, write=SetDisplayName};

Description

Use Name to uniquely specify an individual action item in code anywhere in the application. For action items, Name is equivalent to the DisplayName property. Therefore, when setting the Name property, the new value must not match the DisplayName of any other action item in the list maintained by TCustomWebDispatcher. Trying to set the Name to a DisplayName that is already in use throws an exception.


TWebActionItem::PathInfo

TWebActionItem	See also

Indicates the path portion of the Uniform Resource Identifier (URI) for which the action item handles requests.

__property System::AnsiString PathInfo = {read=FPathInfo, write=SetPathInfo};

Description

Set PathInfo to the path portion of the URI for the target of any request messages serviced by the action item. TWebDispatcher matches action items to request messages by comparing PathInfo with the path portion of the URI specified as the target of the request. If the PathInfo properties match, and the MethodType matches, TWebDispatcher invokes the OnAction event handler of the action item to respond to the request message.


TWebActionItem events

TWebActionItem	Alphabetically	Legend

In TWebActionItem

OnAction


TWebActionItem events

TWebActionItem	By object	Legend

OnAction


TWebActionItem::OnAction

TWebActionItem	See also 	Example

Occurs when TWebDispatcher matches the action item to a newly-arrived HTTP request message.

typedef void __fastcall (__closure *THTTPMethodEvent)(System::TObject* Sender, TWebRequest* Request,TWebResponse* Response, bool &Handled);

__property THTTPMethodEvent OnAction = {read=FOnAction, write=SetOnAction};

Description

Write an OnAction event handler to respond to HTTP request messages that match the MethodType and PathInfo properties. The Request parameter is the TWebRequest object that encapsulates the HTTP request message. The Response parameter is a TWebResponse object to be filled out by the OnAction method. The Handled parameter is an output parameter that indicates whether the action item completed processing the response message.

In an OnAction event handler, read Request and perform the requested Method if possible. Set the properties of the Response parameter as appropriate. If the OnAction event handler does not service the response, or if it only partially handles the request and must let another action item finish the response, set the Handled parameter to false.

An OnAction event handler can call the SendRedirect or SendResponse method of Response to send the HTTP response message to the Web client. If the OnAction event handler does not send the response, the Web application will send it after all action items have finished filling in the Response.

Note:	The OnAction event handler can use descendants of TCustomContentProducer to help assemble the contents of the response message.


TWebActionItem methods

TWebActionItem	Alphabetically

In TWebActionItem

~TWebActionItem

AssignTo

TWebActionItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWebActionItem methods

TWebActionItem	By object

~TWebActionItem

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TWebActionItem


TWebActionItem::AssignTo

TWebActionItem	See also

Copies the properties of the action item to another action item.

virtual void __fastcall AssignTo(Classes::TPersistent* Dest);

Description

To assign the value of one action item to another, use the Assign method of the target action item.

AssignTo enables the Assign method of a target action item to copy the properties of a source action item. AssignTo copies the values of the Default, Enabled, MethodType and PathInfo properties to the Dest parameter if it is an action item. If Dest is not an action item, AssignTo calls the parent class’s AssignTo method.


TWebActionItem::TWebActionItem

TWebActionItem	See also

Ceates an instance of TWebActionItem.

__fastcall virtual TWebActionItem(Classes::TCollection* Collection);

Description

Do not call TWebActionItem to create a TWebActionItem object at runtime. Instead, use the new keyword, passing as an argument the TWebActionItems object that will manage the set of action items that includes the new item. Action items created in the action editor at design time are instantiated automatically.

After calling the parent class's constructor, TWebActionItem initializes the Enabled property to true, and sets the action item so that it will match any HTTP request targeted to a URI with an empty PathInfo.


TWebActionItem::~TWebActionItem

TWebActionItem	See also

Destroys an instance of TWebActionItem.

__fastcall virtual ~TWebActionItem(void);

Description

Do not destroy a TWebActionItem object directly in an application. Action items are destroyed by the TWebActionItems object that manages them.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TCollectionItem


TWebActionItems

Hierarchy	Properties	Methods	See also

TWebActionItems is a collection of TWebActionItem objects.

Unit

httpapp

Description

TCustomWebDispatcher uses TWebActionItems to store and manipulate the individual action items it manages. TWebActionItems provides properties and events to

•	Add new action items to the collection.

•	Copy the list of action items from another TWebActionItems.

•	Get the attributes of specified action items in the collection.

•	Empty the collection of action items.


TWebActionItems properties

TWebActionItems	Alphabetically	Legend

In TWebActionItems

Items

WebDispatcher

Derived from TCollection

Count

ItemClass


TWebActionItems properties

TWebActionItems	By object	Legend

Count

ItemClass

Items

WebDispatcher


TWebActionItems::Items

TWebActionItems	See also

Lists the TWebActionItem objects stored by this TWebActionItems object.

__property TWebActionItem* Items[int Index] = {read=GetActionItem, write=SetActionItem };

Description

Use Items to get access to the individual action items stored by the TWebActionItems object. Items is an indexed array, where the first action item has index 0, the second action item has index 1, and so on. Use Items with the Count property to iterate over all the action items in the collection.


TWebActionItems::WebDispatcher

TWebActionItems

Provides access to the dispatcher that uses TWebActionItems to store and manipulate its action items.

__property TCustomWebDispatcher* WebDispatcher = {read=FWebDispatcher};

Description

Read WebDispatcher to get access to the dispatcher object that uses the collection of action items to respond to HTTP request messages.


TWebActionItems methods

TWebActionItems	Alphabetically

In TWebActionItems

~TWebActionItems

Add

TWebActionItems

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWebActionItems methods

TWebActionItems	By object

~TWebActionItems

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TWebActionItems


TWebActionItems.Add

TWebActionItems	See also

Adds a new action item to the end of the collection.

HIDESBASE TWebActionItem* __fastcall Add(void);

Description

Call Add to add an action item to the collection of action items managed by the dispatcher. The new item is added to the end of the Items array. Add returns the action item so that its properties can be set to specify its use.

Because the dispatcher looks through the action items in order when it tries to find an action item to handle an HTTP request message, add any action items that preprocess HTTP requests first. Then add the most specific action items. This way, more general action items will not be matched to request messages before a closer match can be found.


TWebActionItems::TWebActionItems

TWebActionItems	See also

Creates an instance of TWebActionItems.

__fastcall TWebActionItems(TCustomWebDispatcher* WebDispatcher, System::TMetaClass* ItemClass);

Description

Do not call the constructor for TWebActionItems. TWebActionItems is tailored to work with TCustomWebDispatcher. The TCustomWebDispatcher object creates TWebActionItems in its own constructor.


TWebActionItems::~TWebActionItems

TWebActionItems

~TWebActionItems frees the memory associated with the TWebActionItems object.

__fastcall virtual ~TWebActionItems(void) { }

Description

Do not call ~TWebActionItems directly. TWebActionItems objects are destroyed by the web dispatchers that use them.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


 TAnimate

Hierarchy	Properties	Methods	Events	See also

TAnimate is a wrapper for a Windows animation control.

Unit

comctrls

Description

Use TAnimate to put an animation control on a form. An animation control is a window that silently displays an Audio Video Interleaved (AVI) clip. An AVI clip is a series of bitmap frames like a movie. Although AVI clips can have sound, animation controls only work with silent AVI clips. TAnimate works with uncompressed AVI files or AVI clips compressed using run-length encoding (RLE).

TAnimate can obtain its AVI clip from an AVI resource, and AVI file, or, if the application is running under Windows 95 or NT 4.0, from Shell32.dll.

At design time, you can browse through the frames of the AVI clip specified in FileName, CommonAVI, ResName, or ResID by right-clicking on the TAnimate component and choosing Next Frame or Previous Frame.


TAnimate properties

TAnimate	Alphabetically	Legend

In TAnimate

Active

AutoSize

Center

CommonAVI

FileName

FrameCount

FrameHeight

FrameWidth

Open

Repetitions

ResHandle

ResID

ResName

StartFrame

StopFrame

Timers

Transparent

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ParentShowHint

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TAnimate properties

TAnimate	By object	Legend

Active

Align

AutoSize

BoundsRect

Brush

Center

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

CommonAVI

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

FileName

FrameCount

FrameHeight

FrameWidth

Handle

Height

HelpContext

Hint

Left

Name

Open

Owner

Parent

ParentColor

ParentShowHint

ParentWindow

Repetitions

ResHandle

ResID

ResName

ShowHint

Showing

StartFrame

StopFrame

TabOrder

TabStop

Tag

Timers

Top

Transparent

VCLComObject

Visible

Width

WindowProc


TAnimate::Active

TAnimate	See also 	Example

Indicates whether the animation control is playing the AVI clip.

__property bool Active = {read=FActive, write=SetActive, nodefault};

Description

Set Active to true to cycle through the frames specified by the StartFrame and StopFrame properties by the number of iterations specified in the Repetitions property. Set Active to false to interrupt the animation control when it is playing the AVI clip.

The animation control must be Open before it can be Active.


TAnimate::AutoSize

TAnimate	See also

Determines whether the animation control adjusts its size to the frames in the AVI clip.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=1};

Description

Set AutoSize to true to have the animation control automatically size itself to the size of the frames in the AVI clip. Set AutoSize to false to make the animation control fixed in size. When AutoSize is false, the frames of the AVI clip may not take up the entire client area of the control, or they may appear clipped if they are larger than the client area of the control.

Note:	If the value of the Align property is not alNone, setting AutoSize to true only resizes the sides of the animation control that are not sized to match the parent control.


TAnimate::Center

TAnimate	See also

Determines whether the frames of the AVI clip are centered in the animation control.

__property bool Center = {read=FCenter, write=SetCenter, default=1};

Description

Use Center to position the frames of the AVI clip in the animation control when FrameHeight is not the same as ClientHeight or FrameWidth is not the same as ClientWidth. When Center is true, the frames are centered both horizontally and vertically in the client area of the control. When Center is false, the top left corner of the frames is positioned at the top left corner of the client area.


TAnimate::CommonAVI

TAnimate	See also	Example

Indicates whether the animation control displays a one of the common Windows AVI clips provided in Shell32.dll.

enum TCommonAVI { aviNone, aviFindFolder, aviFindFile, aviFindComputer, aviCopyFiles, aviCopyFile, aviRecycleFile, aviEmptyRecycle, aviDeleteFile };

__property TCommonAVI CommonAVI = {read=FCommonAVI, write=SetCommonAVI, default=0};

Description

Set CommonAVI to display one of the common Windows AVI clips in the animation control. The common Windows AVI clips appear in the Windows user interface when the user attempts common file actions. CommonAVI is aviNone when the animation control displays an AVI clip that was specified in some other manner.

Setting CommonAVI automatically sets the FileName property to an empty string, ResHandle and ResID to 0, and ResName to an empty string.

Note:	CommonAVI cannot be used when running under NT 3.51.


TAnimate::FileName

TAnimate	See also

Specifies the name of the file that contains the AVI clip displayed by the animation control.

__property System::AnsiString FileName = {read=FFileName, write=SetFileName};

Description

Set FileName to use the animation control to display the AVI clip stored in a file. FileName must be the name of a file containing a silent AVI clip.

Note:	Setting FileName automatically sets the CommonAVI property to aviNone, ResHandle and ResID to 0, and ResName to an empty string.


TAnimate::FrameCount

TAnimate	See also

Indicates the total number of frames in the AVI clip.

__property int FrameCount = {read=FFrameCount, nodefault};

Description

Read FrameCount to determine the number of frames that can be displayed by the animation control. The animation control can play all the frames in the AVI clip, or run through a subset of those frames.


TAnimate::FrameHeight

TAnimate	See also

Indicates the height, in pixels, of each image in the AVI clip.

__property int FrameHeight = {read=FFrameHeight, nodefault};

Description

Read FrameHeight to determine the height required to fully display the frames of the AVI clip. If AutoSize is true, the animation control automatically sizes itself to the value of FrameHeight.


TAnimate::FrameWidth

TAnimate	See also

Indicates the width, in pixels, of each image in the AVI clip.

__property int FrameWidth = {read=FFrameWidth, nodefault};

Description

Read FrameWidth to determine the width required to fully display the frames of the AVI clip. If AutoSize is true, the animation control automatically resizes itself to the value of FrameWidth.


TAnimate::Open

TAnimate	See also

Indicates whether the AVI clip is loaded into memory.

__property bool Open = {read=FOpen, write=SetOpen, nodefault};

Description

Read Open to determine whether the AVI clip is loaded and ready for playing. When the AVI clip is specified using the CommonAVI, FileName, ResName, or ResID property, the animation control is opened automatically. When Open is true, the animation control displays the frame specified by the StartFrame property until the clip is played using the Active property or Play method.

Set Open to false to free the resources used by the AVI clip. When the animation control is not open, none of the frames can be shown.

Note:	When Open is changed from false to true, the StartFrame property is reset to 1 and the StopFrame property is reset to FrameCount.


TAnimate::Repetitions

TAnimate	See also

Specifies the number of times to repeat the sequence of frames.

__property int Repetitions = {read=FRepetitions, write=SetRepetitions, default=0};

Description

Set Repetitions to specify the number of times the sequence of frames in the AVI clip is repeated when the Active property is set to true. After the sequence is repeated by the specified number of times, the value of Active becomes false again.

To show the sequence a single time, set Repetitions to 1. Set Repetitions to 0 to indicate that the sequence of frames should repeat indefinitely. When Repetitions is 0, use the Active property or Stop method to interrupt the animation.

Note:	The Play method overrides Repetitions with the value passed as the Count parameter.


TAnimate::ResHandle

TAnimate	See also

Specifies the Windows handle for the module that contains the AVI clip as a resource.

__property int ResHandle = {read=FResHandle, write=SetResHandle, nodefault};

Description

Set ResHandle at runtime to the instance handle or module handle of the module that includes the animation resource. After setting ResHandle, set the ResID or ResName property to specify which resource in the indicated module is the AVI clip that should be displayed by the animation control.

If a value is not specified for ResHandle, the animate control uses the instance of the application’s main executable.

Note:	Setting ResHandle automatically sets the CommonAVI property to aviNone and the FileName property to an empty string.


TAnimate::ResID

TAnimate	See also

Specifies the resource ID of the AVI clip.

__property int ResId = {read=FResId, write=SetResId, nodefault};

Description

Set ResID to identify a resource that should be used as the AVI clip displayed by the animation control. Use ResHandle to indicate the module that contains the resource identified by ResID.

If the resource file identifies the AVI clip by name rather than number, use the ResName property instead.

Note:	Setting ResID automatically sets the CommonAVI property to aviNone, the FileName property to an empty string, and the ResName property to an empty string.


 TAnimate::ResName

TAnimate	See also

Specifies the resource name of the AVI clip.

__property System::AnsiString ResName = {read=FResName, write=SetResName};

Description

Set ResName to identify a resource that should be used as the AVI clip displayed by the animation control. Use ResHandle to indicate the module that contains the resource identified by ResName.

If the resource file identifies the AVI clip by number rather than number, use the ResID property instead.

Note:	Setting ResName automatically sets the CommonAVI property to aviNone, the FileName property to an empty string, and the ResID property to 0.


TAnimate::StartFrame

TAnimate	See also

Specifies the first frame displayed when the animation control is activated.

__property short StartFrame = {read=FStartFrame, write=SetStartFrame, default=1};

Description

Set StartFrame to specify the first frame in the AVI clip that is shown when the Active property is set to true. When StartFrame is 1, the clip is played from the very beginning, when StartFrame is 2, the clip begins with the second frame, and so on. If Repetitions is not 1, after the sequence of frames is played, it starts over at the frame specified by StartFrame (which may not be the first frame in the clip).

When the animation control is Open but not Active, it displays the frame specified by StartFrame.

Note:	The Play method overrides StartFrame with the value passed as the FromFrame parameter.


TAnimate::StopFrame

TAnimate	See also

Specifies the last frame displayed when the animation control is activated.

__property short StopFrame = {read=FStopFrame, write=SetStopFrame, default=0};

Description

Set StopFrame to specify the last frame in the AVI clip that is shown every time the animation control displays its sequence of frames. When StopFrame is 0, the clip is played to the very end. Otherwise, StopFrame is the number of the frame in the sequence. When the Active property is set to true, the animation control displays the sequence of frames from StartFrame to StopFrame, repeating this sequence by the number of iterations specified by the Repetitions property.

Note:	The Play method overrides StopFrame with the value passed as the ToFrame parameter.


TAnimate::Timers

TAnimate	See also

Specifies whether the frames are displayed using a timer.

__property bool Timers = {read=FTimers, write=SetTimers, default=0};

Description

Set Timers to specify whether the frames in the AVI clip should be changed in response to timer messages, or whether the sequence progresses asynchronously in a separate execution thread. When Timers is true, the frames progress in response to timer messages. This is useful for synchronizing the animation sequence with other actions such as playing a sound track. When Timers is false, the AVI clip is played in a separate thread.


TAnimate::Transparent

TAnimate	See also

Specifies whether the background color of the frame matches the Color property.

__property bool Transparent = {read=FTransparent, write=SetTransparent, default=1};

Description

Set Transparent to true to replace the background color stored in the AVI file with the value of the Color property, or the parent control’s color if the value of ParentColor is true. Set Transparent to false to display the background color stored in the AVI clip.


TAnimate events

TAnimate	Alphabetically	Legend

In TAnimate

OnClose

OnOpen

OnStart

OnStop


TAnimate events

TAnimate	By object	Legend

OnClose

OnOpen

OnStart

OnStop


TAnimate::OnClose

TAnimate	See also

Occurs immediately after the animation control is closed.

__property Classes::TNotifyEvent OnClose = {read=FOnClose, write=FOnClose};

Description

Write an OnClose event handler to take specific action when the Open property is set to false. For example, if the animation control is used to cycle through a series of AVI clips, the clip could be changed in an OnClose event handler.

To respond when the clip stops playing, but the animation control remains open, use the OnStop event.


TAnimate::OnOpen

TAnimate	See also

Occurs immediately after the animation control is opened.

__property Classes::TNotifyEvent OnOpen = {read=FOnOpen, write=FOnOpen};

Description

Write an OnOpen event handler to take specific action when the Open property changes from false to true. This is a good opportunity to set the Repetitions, StartFrame, and StopFrame properties before the AVI clip is activated, or to seek to a particular frame.


TAnimate::OnStart

TAnimate	See also

Occurs immediately after the animation control starts playing.

__property Classes::TNotifyEvent OnStart = {read=FOnStart, write=FOnStart};

Description

Write an OnStart event handler to take specific action when the AVI clip is played. Setting the Active property to true or calling the Play method triggers an OnStart event. OnStart is useful for launching other actions that should be synchronized with the playing of the animation sequence.


TAnimate::OnStop

TAnimate	See also

Occurs when the animation control finishes playing.

__property Classes::TNotifyEvent OnStop = {read=FOnStop, write=FOnStop};

Description

Write an OnStop event handler to take specific action when the AVI clip finishes playing all its repetitions. For example, use an OnStop event handler to shut down any simultaneous actions that were started in an OnStart event handler.


TAnimate methods

TAnimate	Alphabetically

In TAnimate

~TAnimate

Play

Reset

Seek

Stop

TAnimate

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TAnimate methods

TAnimate	By object

~TAnimate

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Play

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

Reset

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

Seek

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

Stop

TAnimate

Update

UpdateControlState


TAnimate::TAnimate

TAnimate	See also	Example

Creates and initializes an animation control.

__fastcall virtual TAnimate(Classes::TComponent* AOwner);

__fastcall TAnimate(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Call TAnimate indirectly, using the new keyword, to instantiate an animation control at runtime. Animation controls placed on forms at design time are created automatically.

Pass a single Component as a parameter to provide the animation control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the animation control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TAnimate initializes the following properties:

•	AutoSize is set to true.

•	Center is set to true.

•	ControlStyle is set to [csReflector].

•	StartFrame is set to 1.

•	Transparent is set to true.


TAnimate::Play

TAnimate	See also

Displays a sequence of frames from the AVI clip.

void __fastcall Play(Word FromFrame, Word ToFrame, int Count);

Description

Call Play to display the specified sequence of frames, repeating the sequence Count times. FromFrame is the first frame in the sequence, where 1 specifies the first frame in the clip, 2 specifies the second frame, and so on. ToFrame is the last frame in the sequence. The value of ToFrame should be greater than or equal to FromFrame and less than or equal to the value of the FrameCount property. Count specifies the number of times the sequence should be repeated. If Count is 0, the sequence is repeated until the Stop method is called.

If the animation control is not Open when Play is called, Play sets Open to true.

Note:	Calling Play is the same as setting StartFrame to FromFrame, StopFrame to ToFrame, Repetitions to Count, and then setting Active to true.


TAnimate::Reset

TAnimate	See also

Clears the values of StartFrame and StopFrame, and displays the first frame in the AVI clip.

void __fastcall Reset(void);

Description

Call Reset to restore the animation control to a default state. Reset closes and reopens the animation control, generating OnClose and OnOpen events. The animation control is left open but not active.


TAnimate::Seek

TAnimate	See also

Displays a specified frame in the sequence.

void __fastcall Seek(short Frame);

Description

Call Seek to move to a particular frame in the AVI clip. The Frame parameter specifies which frame, where 1 is the first frame in the sequence, 2 is the second frame, and so on. Frame must be a value less than or equal to FrameCount.

If the animation control is not open when Seek is called, Seek sets Open to true.


TAnimate::Stop

TAnimate	See also

Interrupts the animation control when it is playing.

void __fastcall Stop(void);

Description

Call Stop to halt the sequence of images in an active animation control. Stop does the same thing as setting the Active property to false.


TAnimate::~TAnimate

TAnimate

Frees the memory associated with the TAnimate object.

__fastcall virtual ~TAnimate(void) { }

Description

Do not call ~TAnimate directly. Instead, use the delete keyword on the object, which causes ~TAnimate to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TWebApplication

Hierarchy	Properties	Methods	See also

TWebApplication encapsulates a Web server application.

Unit

httpapp

Description

TWebApplication provides the fundamental behavior of a Web server application. TWebApplication provides methods to create TWebRequest and TWebResponse objects that represent HTTP request messages and their responses, pass these objects to the dispatcher so that the response can be filled in, and send the response back to the Web client.

Each Web server project automatically declares an Application variable of type TWebApplication as the instance of the application. For CGI applications, this variable is initialized to a TCGIApplication object in the CGIApp unit source. For ISAPI applications, this variable is initialized to a TISAPIApplication object in the ISAPIApp unit source.

The Application variable is added to a project by selecting File | New from the menu of the C++Builder main window and selecting Web Server Application in the New Items dialog. Do not include Forms.hpp in the project source file, because that header declares a conflicting Application variable of type TApplication. In addition, do not link ISAPIApp.dcu to a CGI application or CGIApp.dcu to an ISAPI or NSAPI application. The CGIApp unit and the ISAPIApp unit each create the initial instance of the Application variable.


TWebApplication properties

TWebApplication	Alphabetically	Legend

In TWebApplication

ActiveCount

CacheConnections

InactiveCount

MaxConnections

Title

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TWebApplication properties

TWebApplication	By object	Legend

ActiveCount

CacheConnections

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

DesignInfo

InactiveCount

MaxConnections

Name

Owner

Tag

Title

VCLComObject


TWebApplication::ActiveCount

TWebApplication	See also

Indicates the number of active connections currently being serviced by the application.

__property int ActiveCount = {read=GetActiveCount, nodefault};

Description

Use ActiveCount to monitor the number of HTTP request messages the application is servicing at any one time. Over time, this value provides an indication of the optimal value for the MaxConnections property.

Each time an ISAPI application receives an HTTP request message, it generates a new instance of the Web module. After the response is returned to the Web client, the Web module is either destroyed or deactivated and cached for later reuse. Each active Web module resides in a separate execution thread.

ActiveCount is the number of Web modules currently in use. InactiveCount is the number of deactivated Web modules cached for later reuse. MaxConnections is the maximum number of Web modules that can be active at any time. ActiveCount can never exceed MaxConnections.

Note:	ActiveCount is only meaningful for ISAPI applications. Each CGI application handles only a single request message.


TWebApplication::CacheConnections

TWebApplication	See also

Determines whether the Web modules used by the application are cached for re-use.

__property bool CacheConnections = {read=FCacheConnections, write=SetCacheConnections, nodefault};

Description

Each time an ISAPI or NSAPI application receives an HTTP request message, it spawns a thread to handle the request and creates a new Web module that contains instances of all the objects used in the Web application. To improve performance, these Web modules can be saved in a cache when the thread associated with the HTTP request message finishes executing.

Set CacheConnections to true to have the Web application save inactive Web modules in a cache. Caching the Web modules speeds performance as new instances of the Web module and its contents do not need to be created every time a request message is received. Set CacheConnections to false to have the Web application create a new Web module for every request thread. Recreating the Web module ensures that changes made to the module or its contents when servicing the last request do not cause unexpected behavior the next time the module is activated.

Note:	CacheConnections is only relevant to ISAPI and NSAPI Web applications.


TWebApplication::InactiveCount

TWebApplication	See also

Indicates the number of Web modules cached for later reuse.

__property int InactiveCount = {read=GetInactiveCount, nodefault};

Description

Use InactiveCount to monitor the number of unused Web modules. Over time, this value provides an indication of the optimal value for the MaxConnections property.

When CacheConnections is true, each time an ISAPI application receives an HTTP request message, it reactivates one of the inactive Web modules. The application generates a new instance of the Web module if InactiveCount is 0. After the response is returned to the Web client, the Web module is deactivated again, and counted by the InactiveCount property.

When CacheConnections is false, a new Web module is created for each HTTP request message and destroyed when the response is returned. InactiveCount is always 0 when CacheConnections is false.

Note:	InactiveCount is only meaningful for ISAPI applications. Each CGI application handles only a single request message, so there is no need to cache unused data modules.


TWebApplication::MaxConnections

TWebApplication	See also

Specifies the maximum number of request messages the application can handle at any one time.

__property int MaxConnections = {read=FMaxConnections, write=FMaxConnections, nodefault};

Description

Set MaxConnections to adjust the number of HTTP request messages the application can handle simultaneously. Use the ActiveCount and InactiveCount properties to get a sense of the frequency and duration of request messages. Then set MaxConnections so that it is high enough to avoid exceptions when the application runs out of Web modules, but low enough not to degrade performance too severely by running too many simultaneous threads.

If a request message is received when ActiveCount is already at MaxConnections, the application throws an exception.

Note:	MaxConnections is only meaningful for ISAPI applications. Each CGI application handles only a single request message.


TWebApplication::Title

TWebApplication	See also

Contains the text that appears below the icon representing the application when it is minimized.

__property System::AnsiString Title = {read=FTitle, write=FTitle};

Description

Use the Title property to modify the name of this text string appearing below the icon of the application. The default value is taken from the DLL/EXE filename at run-time.

Do not confuse Title with the Name property. Name is the identifier for the Web application when it is referred to in code.


TWebApplication methods

TWebApplication	Alphabetically	Legend

In TWebApplication

~TWebApplication

ActivateWebModule

CreateForm

DeactivateWebModule

DoHandleException

HandleRequest

Initialize

Run

TWebApplication

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TWebApplication methods

TWebApplication	By object	Legend

~TWebApplication

ActivateWebModule

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateForm

DeactivateWebModule

DefaultHandler

DestroyComponents

Destroying

Dispatch

DoHandleException

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HandleRequest

HasParent

InheritsFrom

Initialize

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

Run

SafeCallException

TWebApplication


TWebApplication::ActivateWebModule

TWebApplication	See also

Activates a Web module for the application and returns it.

Forms::TDataModule* __fastcall ActivateWebModule(void);

Description

ActivateWebModule is called internally when the application receives an HTTP request message. If the InactiveCount property is greater than zero, a cached Web module is reactivated. Otherwise, a new instance of the Web module is created.

Before ActivateWebModule is called, the CreateForm method must be called to register the data module.

A Web application object contains only a single Web module. Usually, that Web module is a TWebModule object, but it may also be an ordinary data module that contains a TWebDispatcher object. If there is no Web module associated with the Web application, ActivateWebModule throws an exception. If the ActiveCount property is already at MaxConnections when ActivateWebModule is called, ActivateWebModule throws an exception.


TWebApplication::TWebApplication

TWebApplication	See also

Creates an instance of TWebApplication.

__fastcall virtual TWebApplication(Classes::TComponent* AOwner);

Description

Do not call TWebApplication. The single Web application object named Application is instantiated automatically by the project.

TWebApplication allocates the helper objects used by TWebApplication.


TWebApplication::TWebApplication
TWebApplication::CreateForm

TWebApplication	See also

Registers the single Web module with the Web application.

virtual void __fastcall CreateForm(System::TMetaClass* InstanceClass, void *Reference);

Description

Do not call CreateForm in an application. C++Builder’s module manager calls CreateForm internally to register the Web module for the Web application.

CreateForm registers the class of the Web module for the application. The Web module object is created later when the ActivateWebModule method is called for the first time.


TWebApplication::DeactivateWebModule

TWebApplication	See also

Deactivates the Web module of the application.

void __fastcall DeactivateWebModule(Forms::TDataModule* DataModule);

Description

Do not call DeactivateWebModule directly. The Web application calls DeactivateWebModule internally after handling an HTTP request message. When CacheConnections is true, the Web module remains inactive until the next request message is received. When CacheConnections is false, the runtime instance of the Web module is destroyed.


TWebApplication::~TWebApplication

TWebApplication	See also

Destroys an instance of TWebApplication.

__fastcall virtual ~TWebApplication(void);

Description

Never call ~TWebApplication or use the delete keyword on the TWebApplication object. The application is freed automatically when the application stops running.

~TWebApplication frees the helper objects that were created at startup, as well as all Web modules created by the application.


TWebApplication::DoHandleException

TWebApplication	See also

Provides the interface for a method that handles exceptions thrown within the application.

DYNAMIC void __fastcall DoHandleException(Sysutils::Exception* E);

Description

The DoHandleException method for TWebApplication discards all exceptions. Descendants of TWebApplication can override this method to provide special responses when exceptions occur within the application.


TWebApplication::HandleRequest

TWebApplication	See also

Responds to an HTTP request message received by the server.

bool __fastcall HandleRequest(TWebRequest* Request, TWebResponse* Response);

Description

When a descendant of TWebApplication receives an HTTP request message, it creates a TWebRequest object to represent the message, and a TWebResponse message to match the request. It then calls HandleRequest, passing those objects as the Request and Response parameters.

HandleRequest activates the Web module associated with the Web application. It then passes the request and response objects to the dispatcher, so that it can dispatch the request to the appropriate action items. When the dispatcher returns, HandleRequest checks whether the response was handled but not sent, and if not, sends it. Finally, HandleRequest deactivates the data module.

HandleRequest returns a boolean value indicating whether the request message was handled and sent.


TWebApplication::Initialize

TWebApplication	See also

Introduces an interface for a method that initializes the application.

virtual void __fastcall Initialize(void);

Description

The Initialize method for TWebApplication does nothing. Initialize is the first method called for every C++Builder project. Descendants of TWebApplication that must perform any initialization before the application starts running override this method for that purpose.

Note:	Although Initialize is the first method called in the project source code, it is not the first code that is executed in an application.


TWebApplication.Run

TWebApplication	See also

Executes the Web application.

virtual void __fastcall Run(void);

Description

When the application is executed, the application’s Run method is called automatically.

The Run method for TWebApplication sets up the default error handler and shut down sequence for the application. Descendants of TWebApplication override the Run method to receive HTTP request messages, create the TWebRequest and TWebResponse objects for incoming requests, and call the HandleRequest method to process those requests.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TApplication

Hierarchy	Properties	Methods	Events	See also

TApplication is the type used for a C++Builder application.

Unit

forms

Description

TApplication encapsulates a windows application. The methods and properties introduced in TApplication reflect the fundamentals established in the Windows operating system to create, run, sustain, and destroy an application. TApplication thereby simplifies the interface between the user and the Windows environment when writing a Windows application. For this purpose, TApplication encapsulates behavior for

•	Windows message processing

•	Context-sensitive online help

•	Menu accelerator and key processing

•	Exception handling

•	Managing the fundamental parts defined by the Windows operating system for an application, such as MainWindow, WindowClass, and so on

Each C++Builder application automatically declares an Application variable as the instance of the application. If the C++Builder application is not a Web server application, this variable is of type TApplication. Therefore, TApplication does not need to appear on the Component palette, nor is it available in the form designer to visually manipulate; so it has no published properties. Nevertheless, some of its public properties can be set or modified at design time in the Forms and Application pages of the Project|Options dialog box.


TApplication properties

TApplication	Alphabetically	Legend

In TApplication

Active

AllowTesting

DialogHandle

ExeName

Handle

HelpFile

Hint

HintColor

HintHidePause

HintPause

HintShortPause

Icon

MainForm

ShowHint

ShowMainForm

Terminated

Title

UpdateFormatSettings

UpdateMetricSettings

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TApplication properties

TApplication	By object	Legend

Active

AllowTesting

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

DialogHandle

ExeName

Handle

HelpFile

Hint

HintColor

HintHidePause

HintPause

HintShortPause

Icon

MainForm

Name

Owner

ShowHint

ShowMainForm

Tag

Terminated

Title

UpdateFormatSettings

UpdateMetricSettings

VCLComObject


TApplication::Active

TApplication	See also

Specifies whether the application is active and has focus.

__property bool Active = {read=FActive, nodefault};

Description

Active is read-only. Active is true while the application is active and false if it is not. Active is set to true in the constructor.

An application is active if the form or application has focus. An application becomes inactive when a window from a different application is about to become activated. When the application closes, Active is set to false in the destructor.


TApplication::AllowTesting

TApplication

Represents information for the IDE.

__property bool AllowTesting = {read=FAllowTesting, write=FAllowTesting, nodefault};

Description

Do not use AllowTesting; it is for internal use only.


TApplication::DialogHandle

TApplication	See also

Provides a mechanism for using non-C++Builder dialog boxes in a C++Builder application.

__property HWND DialogHandle = {read=GetDialogHandle, write=SetDialogHandle, nodefault};

Description

Use DialogHandle when displaying a modeless dialog box that was created using the CreateDialog API function. Assigning the handle of the modeless dialog box to DialogHandle allows the dialog to see messages from the application's message loop.

Assign the handle of the modeless dialog box to DialogHandle when it receives an activation message (WM_NCACTIVATE) and set DialogHandle to zero when the dialog box receives a deactivation message.


TApplication::ExeName

TApplication	See also	Example

Contains the file name of the executable application including path information.

__property System::AnsiString ExeName = {read=GetExeName};

Description

ExeName is a read-only property. Use ExeName to obtain the name of the executable file for the application.

The name of the application is the root name of the project with an .EXE extension. By default, this name is PROJECT1.EXE. To change the ExeName, save the project by the desired new root name and rebuild the application. ExeName will reflect the change to the project file name.


TApplication::Handle

TApplication	See also

Provides access to the window handle of the main form (window) of the application.

__property HWND Handle = {read=FHandle, write=SetHandle, nodefault};

Description

Use Handle when calling a Windows API functions that require a parent window handle. For example, a DLL that displays its own top-level pop-up windows will need a parent window to display its windows in the application. Using Application->Handle makes such windows part of the application, so that they will be minimized, restored, enabled, and disabled using the application.

Note:	When writing a DLL that uses VCL forms, assign the window handle of the host EXE’s main window to the DLL’s Application->Handle property. This makes the DLL’s form part of the host application. Never assign to Application->Handle in an EXE.


TApplication::HelpFile

TApplication	See also 	Example

Specifies the name of the file the application uses to display Help.

__property System::AnsiString HelpFile = {read=FHelpFile, write=FHelpFile};

Description

Use HelpFile for applications that have a help file to use with the Windows Help system. Windows displays the file specified by the HelpFile property. Either assign a file name to the HelpFile property at runtime, or specify a Help File on the Application page of the Project|Options dialog box at design time.

By default, HelpFile is a null string, and the application's Help method ignores attempts to display Help. If HelpFile contains anything, the HelpContext method passes it to the Windows Help system as the name of the file to use for Help.

Note:	The active form’s help file is displayed rather than the application’s help file, if it has been assigned.


TApplication::Hint

TApplication	See also 	Example

Specifies the text string that appears in the Help Hint box.

__property System::AnsiString Hint = {read=FHint, write=SetHint};

Description

TApplication’s Hint property is assigned the Hint value of the control or menu item that the mouse is currently moving over. It can also be assigned a string value that informs the user of some action, error, or other type of information. Therefore, use Hint either to

•	Transfer hints from controls to another area of display, such as a status bar, using the OnHint event handler. This reads the Hint property.

•	Indicate the status of the application while it is processing some action. This sets the Hint property.

Help Hints appear when the OnHint event occurs. Therefore, if TApplication’s Hint property is assigned to the status bar’s caption, for example, the caption of the status bar control displays the current string value of the Hint property during an OnHint event.

There are two parts to the Hint string: short and long. Short hints are used by pop-up tool tips. Long hints are used by the status bar, separated by the | character. Use the global functions GetShortHint and GetLongHint, from the Controls header file, to extract the long and short hints from a hint string.

Note:	When setting Hint to a message informing the user of an event occurring in the application, remember that, by default, the Hint string is reset to a control’s Hint when the mouse cursor moves over a control.


TApplication::HintColor

TApplication	See also	Example

Determines the color of the hint boxes for the Help Hints for the application.

__property Graphics::TColor HintColor = {read=FHintColor, write=SetHintColor, nodefault};

Description

Use HintColor to specify the hint box color. A default color value of clInfoBk is set for the HintColor property in the constructor when the application is created. To change the HintColor, assign it a new TColor value at runtime.


TApplication::HintHidePause

TApplication	See also

Specifies the time interval to wait before hiding the Help Hint if the mouse has not moved from the control or menu item.

__property int HintHidePause = {read=FHintHidePause, write=FHintHidePause, nodefault};

Description

Use HintHidePause to specify a wait time in milliseconds, which is different from the default value of 2500 ms or 2 1/2 seconds that is set in the constructor. The Help Hint for the control or menu item is specified in the Hint property.

Note:	The default is a predefined const value that is several times longer than HintPause.


TApplication::HintPause

TApplication	See also	Example

Specifies the time interval that passes before the control's Help Hint appears when the user places the mouse pointer on a control or menu item.

__property int HintPause = {read=FHintPause, write=FHintPause, nodefault};

Description

Use HintPause to change the default pause time of 500 ms or 1/2 second which is set in the constructor. When assigning a value to HintPause specify the interval in milliseconds. The Help Hint displayed at the end of the pause is specified in the Hint property.


TApplication::HintShortPause

TApplication	See also

Specifies the pause to wait before bringing up a hint if a hint has already been shown.

__property int HintShortPause = {read=FHintShortPause, write=FHintShortPause, nodefault};

Description

Use HintShortPause to reduce the flicker when moving the mouse quickly over a set of buttons that all have help hints on. Specify a value in milliseconds that is different from the default value of 50 ms which is set in the constructor.


TApplication::Icon

TApplication	See also 	Example

Determines which icon represents the application on the Windows task bar.

__property Graphics::TIcon* Icon = {read=FIcon, write=SetIcon};

Description

Use Icon to assign a specific icon to represent the application. Set the Icon property by either:

•	Assigning it a TIcon at runtime.

•	Loading an icon on the Application pages of the Project|Options dialog box at design time.

Icon represents the application when it is minimized and appears either on the Windows desktop or on the task bar in Windows 95.


TApplication::MainForm

TApplication	See also

Identifies which form in the application is the main window.

__property TForm* MainForm = {read=FMainForm};

Description

Use MainForm to specify a form, different from the default, as the main window of the application. This value is set to be the first form created via the CreateForm method. When a new project is created, Form1 automatically becomes the value of the MainForm property. To assign a different form to the MainForm property, use the Forms page of the Project|Options dialog box at design time. MainForm cannot be modified at runtime because it is read-only.

The main form is the first form created in the main body of the application. When the main form closes, the application terminates.


TApplication::ShowHint

TApplication	See also 	Example

Determines whether Help Hints are enabled or disabled for the entire application.

__property bool ShowHint = {read=FShowHint, write=SetShowHint, nodefault};

Description

Use ShowHints to choose when to display Help Hints. If ShowHint is true, Help Hints are enabled; if ShowHint is false, Help Hints are disabled. The default value is true. Help Hints are specified in the Hint property.

Setting ShowHint for the application to false disables all Help Hints, regardless of the value of the ShowHint properties for individual controls.


TApplication::ShowMainForm

TApplication	See also

Determines whether the application shows its main form on startup.

__property bool ShowMainForm = {read=FShowMainForm, write=FShowMainForm, nodefault};

Description

Use ShowMainForm to control whether and when the application shows its main form.

The default value of true is set in the constructor. By default the main window shows. The MainForm property specifies which form is the main form.

To hide the main form at startup, set ShowMainForm to false in the main project file before the call to Application->Run, and make sure that the Visible property of the form is also false. This is mostly useful for implementing OLE automation servers, to hide the server’s main form when started for automation purposes.


TApplication::Terminated

TApplication	See also	Example

Reports whether the application has received the Windows WM_QUIT message, which then terminates the application.

__property bool Terminated = {read=FTerminate, nodefault};

Description

Terminated is read-only. It is used when calling the ProcessMessages method so that the application doesn't attempt to process Windows messages after the application has quit. ProcessMessage sets Terminated to true when it receives a WM_QUIT message.

A C++Builder application usually receives a WM_QUIT message because the main window of the application has closed, or because the Terminate method has been called.

For applications using calculation-intensive loops, call Application->ProcessMessages periodically, and also check Application->Terminated to determine whether or not to abort the calculation so that the application can terminate.


TApplication::Title

TApplication	See also	Example

Contains the text that appears below the icon representing the application when it is minimized.

__property System::AnsiString Title = {read=GetTitle, write=SetTitle};

Description

Use the Title property to modify the name of this text string appearing below the icon of the application. The default value is taken from the DLL/EXE file name at runtime.

Set the Title at runtime, or enter the value of the Title property on the Application page of the Project|Options dialog box.


TApplication::UpdateFormatSettings

TApplication

Specifies whether the format settings are updated automatically when the user alters the system configuration.

__property bool UpdateFormatSettings = {read=FUpdateFormatSettings, write=FUpdateFormatSettings, nodefault};

Description

Use UpdateFormatSettings to control automatic updating of format settings. The default of true is set in the constructor. UpdateFormatSettings is checked when the application receives a WM_WININICHANGE message.

We recommend using the default format settings, which are initialized to the Windows local settings. However, to prevent the settings from changing during the execution of the application when altering the format settings in a C++Builder application, UpdateFormatSettings can be set to false.


TApplication::UpdateMetricSettings

TApplication

Specifies whether the settings used for the hint window font and the icon title font are updated.

__property bool UpdateMetricSettings = {read=FUpdateMetricSettings, write=FUpdateMetricSettings, nodefault};

Description

Use UpdateMetricSettings to specify whether or not the hint window font and the icon title font on the desk top should be updated to reflect the system settings when those settings are changed.

The initial value of true is set in the constructor.


TApplication events

TApplication	Alphabetically

In TApplication

OnActivate

OnDeactivate

OnException

OnHelp

OnHint

OnIdle

OnMessage

OnMinimize

OnRestore

OnShowHint


TApplication events

TApplication	By object

OnActivate

OnDeactivate

OnException

OnHelp

OnHint

OnIdle

OnMessage

OnMinimize

OnRestore

OnShowHint


TApplication::OnActivate

TApplication	See also

Occurs when an application becomes active.

__property Classes::TNotifyEvent OnActivate = {read=FOnActivate, write=FOnActivate};

Description

Use OnActivate to write an event handler to perform special processing when the application becomes activated.

An application becomes active when it is initially run or when focus moves from another Windows application back to any window of the application.


TApplication::OnDeactivate

TApplication	See also 	Example

Occurs when an application becomes inactive.

__property Classes::TNotifyEvent OnDeactivate = {read=FOnDeactivate, write=FOnDeactivate};

Description

Use the OnDeactive event to specify any special processing that should occur immediately before the application becomes deactivated. The OnDeactivate event occurs when the user switches from the application to another Windows application.


TApplication::OnException

TApplication	See also 	Example

Occurs when an unhandled exception occurs in the application.

__property TExceptionEvent OnException = {read=FOnException, write=FOnException};

Description

Use OnException to change the default behavior that occurs during an unhandled exception in the application. The OnException event handler is called automatically in the HandleException method.

OnException only handles exceptions that occur during message processing. Exceptions that occur before or after the execution of Application->Run do not generate OnException events.

If an exception passes through the try blocks in the application code, the application automatically calls the HandleException method. Unless the exception object is EAbort, HandleException calls the OnException handler, if one exists. Otherwise, it calls ShowException to display a message dialog box indicating an error occurred.

The TExceptionEvent type is the type of the OnException event. It points to a method that handles exceptions in the application. The Sender parameter is the object that threw the exception, and E is the exception object.


TApplication::OnHelp

TApplication	See also 	Example

Occurs when the application receives a request for help.

__property Classes::THelpEvent OnHelp = {read=FOnHelp, write=FOnHelp};

Description

Use OnHelp to write an event handler to perform special processing when help is requested. The HelpContext and the HelpJump methods automatically trigger the OnHelp event.

Set CallHelp to true to have the VCL call WinHelp after the event. Set CallHelp to false to prevent the VCL from calling WinHelp.

All application help methods go through OnHelp. Only if OnHelp’s CallHelp parameter returns true, or if OnHelp is not assigned, is WinHelp called.

To find the possible values of the Command and Data parameters, search for WinHelp in the Win32 Developer's Reference Help (Win32.HLP) file, which explains the WinHelp API (application programming interface). The possible values for the Data parameter depend upon the value of the Command parameter.

The return value is true if the function succeeds, false if the function fails.


TApplication::OnHint

TApplication	See also 	Example

Occurs when the mouse pointer moves over a control or menu item that can display a Help Hint.

__property Classes::TNotifyEvent OnHint = {read=FOnHint, write=FOnHint};

Description

Use OnHint to write an event handler to perform special processing when the OnHint event occurs. OnHint occurs when the user positions the mouse pointer over a control with a Hint property value other than an empty string ('''').

A common use of the OnHint event is to display the value of a control or menu item's Hint property as the caption of a panel control (TStatusBar), thereby using the panel as a status bar. The Hint property can specify a Help Hint and a usually longer hint that appears elsewhere when the OnHint event occurs.


TApplication::OnIdle

TApplication 	Example

Occurs when an application becomes idle.

__property TIdleEvent OnIdle = {read=FOnIdle, write=FOnIdle};

Description

Use OnIdle to write an event handler to perform special processing when an application is idle. An application is idle when it is not processing code. For example, an application is idle when it is waiting for input from the user.

The TIdleEvent type is the type of the OnIdle event. It points to a method that runs when the application is idle. TIdleEvent has a Boolean parameter Done that is true by default. When Done is true, the Windows API WaitMessage function is called when OnIdle returns. WaitMessage yields control to other applications until a new message appears in the message queue of the application. When Done is false, the application does not yield control to other applications while it is not busy.

OnIdle is called only once, as the application transitions into an idle state. It is not called continuously unless Done is set to false. Applications that set Done to false consume an inordinate amount of CPU time, which affects overall system performance.


TApplication::OnMessage

TApplication	See also 	Example

Occurs when the application receives Windows messages.

typedef void __fastcall (__closure *TMessageEvent)(tagMSG &Msg, bool &Handled);

__property TMessageEvent OnMessage = {read=FOnMessage, write=FOnMessage};

Description

Use OnMessage to trap any or all Windows messages posted to all windows in the application. The OnMessage event occurs when an application receives a Windows message. Creating an OnMessage event handler in an application allows other handlers to respond to messages other than those declared in the events for TApplication. If the application doesn't have a specific handler for an incoming message, the message is dispatched to the window for which it was intended, and Windows handles the message.

The TMessageEvent type is the type of the OnMessage event. It points to a method that handles the processing of incoming Windows messages. The Msg parameter identifies the Windows message, and the Handled parameter determines whether the message is handled or not. Set Handled to true, if the message has been completely handled, to prevent normal processing of the message.

Note:	OnMessage only receives messages that are posted to the message queue, not those sent directly with the Windows API SendMessage function.

Caution:	Thousands of messages per second flow though this event. Be careful when coding the handler since it can affect the performance of the entire application.


TApplication::OnMinimize

TApplication	See also 	Example

Occurs when an application is minimized.

__property Classes::TNotifyEvent OnMinimize = {read=FOnMinimize, write=FOnMinimize};

Description

Use OnMinimize to write an event handler to perform special processing when the application is minimized. The application is minimized, either because the user minimizes the main window, or because of a call to the Minimize method. The Icon property determines the icon that represents the minimized application.


TApplication::OnRestore

TApplication	See also

Occurs when the previously minimized application is restored to its normal size.

__property Classes::TNotifyEvent OnRestore = {read=FOnRestore, write=FOnRestore};

Description

Use OnRestore to write an event handler to perform special processing when the application is restored from a minimized state in which it appears as an icon. An application is restored either because the user restores the application, or because the application calls the Restore method.

Note:	Don't confuse restoring an application with restoring a form or window to its original size. To minimize, maximize, and restore a window or form, change the value of the WindowState property.


TApplication::OnShowHint

TApplication	See also 	Example

Occurs when the application is about to display a hint window for a Help Hint for a particular control.

__property TShowHintEvent OnShowHint = {read=FOnShowHint, write=FOnShowHint};

Description

Use OnShowHint to write an event handler that changes the appearance and behavior of Help Hints.

The TShowHintEvent is the type of the OnShowHint event. It points to a method that displays a Help Hint for a control. The HintStr parameter sets the text of the Help Hint. To obtain the text of a hint for a particular control, call the GetLongHint or GetShortHint function, assigning the result to HintStr. To change the text, change the contents of this string.

Use the CanShow variable to permit or prevent the Help Hint from displaying. If CanShow is true, the Help Hint displays. If it is false, the Help Hint does not appear.

The HintInfo parameter is a record that contains information about the appearance and behavior of the Help window.


TApplication methods

TApplication	Alphabetically

In TApplication

~TApplication

BringToFront

CancelHint

ControlDestroyed

CreateForm

CreateHandle

HandleException

HandleMessage

HelpCommand

HelpContext

HelpJump

HideHint

HintMouseMessage

HookMainWindow

Initialize

MessageBox

Minimize

NormalizeAllTopMosts

NormalizeTopMosts

ProcessMessages

Restore

RestoreTopMosts

Run

ShowException

TApplication

Terminate

UnhookMainWindow

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TApplication methods

TApplication	By object

~TApplication

Assign

BringToFront

CancelHint

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ControlDestroyed

CreateForm

CreateHandle

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HandleException

HandleMessage

HasParent

HelpCommand

HelpContext

HelpJump

HideHint

HintMouseMessage

HookMainWindow

InheritsFrom

Initialize

InitInstance

InsertComponent

InstanceSize

MessageBox

MethodAddress

MethodName

Minimize

NewInstance

NormalizeAllTopMosts

NormalizeTopMosts

ProcessMessages

RemoveComponent

Restore

RestoreTopMosts

Run

SafeCallException

ShowException

TApplication

Terminate

UnhookMainWindow


TApplication::BringToFront

TApplication	See also

Sets the last active window as the topmost window on the desktop above all other applications.

void __fastcall BringToFront(void);

Description

Use BringToFront to find the window owned by the MainForm that was last active and bring it to the foreground. BringToFront also tests to see if the window is visible and enabled before making it the topmost window.


TApplication::CancelHint

TApplication	See also

Cancels the displaying of a hint for a control.

void __fastcall CancelHint(void);

Description

Applications rarely, if ever, call CancelHint directly. CancelHint is used internally to cancel the display of hints at appropriate times, such as when a window is not valid or when the application closes. CancelHint calls a series of routines that clean up the display and timing issues of the hint window for a control.


TApplication::ControlDestroyed

TApplication	See also

Notifies the application that a control has been destroyed.

void __fastcall ControlDestroyed(Controls::TControl* Control);

Description

ControlDestroyed is for internal use and is called automatically by TControl. There is no reason to call it directly.

Note:	ControlDestroyed notifies the application that the control passed as the Control parameter has been destroyed, so that the application pointers, such as MainForm and ActiveForm, can be updated to point to a valid control object or to NULL.


TApplication::TApplication

TApplication	See also

Creates a new application.

__fastcall virtual TApplication(Classes::TComponent* AOwner);

Description

Do not call TApplication directly. Each C++Builder application automatically creates an instance of an application object.

For TApplication, the TApplication method sets default values for some of its properties. It also prepares the application to run by setting up, for example, hint windows, the application icon, the main window handle, the HInstance, lists for managing child windows of the main window (form) and so on.


TApplication::TApplication
TApplication::CreateForm

TApplication	See also	Example

Creates a new form.

void __fastcall CreateForm(System::TMetaClass* InstanceClass, void *Reference);

Description

It is seldom necessary to add calls to CreateForm to an application.

A C++Builder project typically contains one or more calls to CreateForm in the project's main source and handles form creation automatically when using the form designer. An application might call CreateFrom to dynamically create a form at runtime.

CreateForm creates a new form of the type specified by the FormClass parameter and assigns it to the variable given by the Reference parameter. The owner of the new form is the Application object. By default, the form created by the first call to CreateForm in a project becomes the project's main form.


TApplication::TApplication
TApplication::CreateHandle

TApplication	See also

Generates a main window for the application if it does not already have one.

void __fastcall CreateHandle(void);

Description

Do not call CreateHandle directly. In EXEs, TApplication::Create calls CreateHandle. In DLLs it does not.

CreateHandle encapsulates much of what traditional Windows programs write in WinMain. For example, CreateHandle registers the Window Class, creates the application window and determines how the application window is shown.


TApplication::~TApplication

TApplication	See also

Destroys the application instance and all of its associated memory.

__fastcall virtual ~TApplication(void);

Description

Never call ~TApplication or use the delete keyword with an application object. Use Application::Terminate to end an application.

~TApplication signals that the application has been deactivated before calling the parent object's destructor. It then frees memory for hooked windows, the object instance, objects, and lists that were created at application startup or that accumulated during execution.

Since the Application (should) owns all forms, it will destroy all forms in its destructor.


TApplication::HandleException

TApplication	See also	Example

Provides default handling of exceptions for the application.

void __fastcall HandleException(System::TObject* Sender);

Description

HandleException is useful for component writers implementing custom components that generate an event that is not in response to a Windows message.

To assign other exception handling code for the application, use the OnException event handler.

If an exception passes through all the try blocks in the application code, the application automatically calls the HandleException method, which displays a dialog box indicating an error occurred. Unless the exception object is EAbort, HandleException calls the OnException handler, if one exists. Otherwise, it calls ShowException to display a message dialog box indicating an error occurred.


TApplication::HandleMessage

TApplication	See also 	Example

Interrupts the execution of an application so that Windows can process a single message in the Windows message queue before returning control to the application.

void __fastcall HandleMessage(void);

Description

If the message queue is empty, HandleMessage calls the application's Idle method, which, in turn, calls the OnIdle event handler if one is defined.

Note:	If the application goes idle HandleMessage may take a long time to return. Therefore, do not call HandleMessage when waiting for something message-based, while priority actions are also being processed. In contrast, call ProcessMessages when processing other actions besides messages.


TApplication::HelpCommand

TApplication	See also 	Example

Provides quick access to any of the Help commands in the WinHelp API (application programming interface).

bool __fastcall HelpCommand(int Command, int Data);

Description

Use HelpCommand to access WinHelp. HelpCommand is a wrapper function that simply calls a method which generates the OnHelp event.

For information about these commands and the data passed to them, see the WinHelp topic in the Windows Help system.


TApplication::HelpContext

TApplication	See also 	Example

Displays the help file for an application.

bool __fastcall HelpContext(Classes::THelpContext Context);

Description

Use HelpContext to bring up the help file for the application specified in the HelpFile property. HelpContext calls OnHelp directly.

HelpContext passes the file name contained in HelpFile and the context number passed in Context parameter. For example, if the Context value is 714, the HelpContext method displays the screen with the context help ID of 714 in the Help file.

HelpContext returns false if HelpFile is an empty string, meaning the application has no Help file assigned. In all other cases, HelpContext returns true.


TApplication::HelpJump

TApplication	See also 	Example

Generates an OnHelp event.

bool __fastcall HelpJump(const System::AnsiString JumpID);

Description

Use HelpJump to bring up Help for the specific topic. HelpJump passes the file name contained in HelpFile and the context string specified in the JumpID parameter. For example, if the JumpID value is 'TApplication_HelpJump', the HelpJump method displays this screen (which has the context string 'TApplication_HelpJump').

HelpJump returns false if HelpFile is an empty string, meaning the application has no Help file assigned. In all other cases, HelpJump returns true.


TApplication::HideHint

TApplication	See also

Hides the current hint.

void __fastcall HideHint(void);

Description

Applications rarely, if ever, call HideHint directly. HideHint is used internally to hide the hint window at the appropriate times according to predetermined conditions and timer values. For example, CancelHint calls HideHint.


TApplication::HintMouseMessage

TApplication	See also

Regulates the display of hint windows.

void __fastcall HintMouseMessage(Controls::TControl* Control, Messages::TMessage &Message);

Description

Applications rarely, if ever, call HintMouseMessage directly. HintMouseMessage is used internally to manage the display of the hint windows.


TApplication::HookMainWindow

TApplication	See also

Enables a non-C++Builder dialog box to receive messages sent to the application’s main window.

void __fastcall HookMainWindow(TWindowHook &Hook);

Description

Use HookMainWindow to ensure that the non-C++Builder dialog box behaves correctly as a child of the application, not as a standalone window. For example, switching among applications with Alt+Tab treats the application as a single task after calling HookMainWindow, rather than treating the non-C++Builder dialog box as a separate task.

When the window identified by the Handle property receives relevant dialog messages, it passes them to the dialog procedure passed as the Hook parameter. This Hook parameter is of type TWindowHook. It is a method-pointer type used for the dialog-procedures of non-C++Builder dialog boxes. The dialog procedure is similar to a window procedure for a window, in that it processes messages for the dialog box, but its syntax is somewhat different.

There is no problem with leaving a dialog box hooked into the main window, even for extended periods. However, should the dialog box close, call the UnhookMainWindow method to release the hook.


TApplication::Initialize

TApplication 	Example

Provides an opportunity to initialize sub-systems such as OLE automation.

void __fastcall Initialize(void);

Description

Initialize is the first method called for every C++Builder project. It calls the InitProc procedure pointer. By default, the call to Initialize for the application does nothing because the default InitProc pointer that is NULL .

To use Initialize, the InitProc pointer must somehow be predefined. This can be accomplished in one of two ways:

•	Include a header file that defines InitProc, such as OleAuto.hpp.

•	Create a custom initialization procedure that assigns a value to the InitProc pointer, and add a call to this procedure to the project source prior to the call to Initialize.

Warning:	Only one instance of InitProc can be defined in an application. If more than one header file assigns a value to InitProc, only the last assignment will work.

For projects that do not assign a value to InitProc, the call to Initialize can be safely deleted from the project source.

Note:	Although Initialize is the first method called in the main project source code, it is not the first code that is executed in an application. The application will first execute the “initialization” section of all the header files used by the application.


TApplication::MessageBox

TApplication 	See also	Example

Displays a specified message to the user.

int __fastcall MessageBox(char * Text, char * Caption, int Flags);

Description

Use MessageBox to displays a generic dialog box a message and one or more buttons. Caption is the caption of the dialog box and is optional.

MessageBox is an encapsulation of the Windows API MessageBox function. TApplication’s encapsulation of MessageBox automatically supplies the missing window handle parameter needed for the Windows API function.

The value of the Text parameter is the message, which can be longer than 255 characters if necessary. Long messages are automatically wrapped in the message box. The value of the Caption property is the caption that appears in the title bar of the dialog box. Captions can be longer than 255 characters, but they don't wrap. A long caption results in a wide message box.

To see the possible values of the Flags parameter, see the MessageBox function in the Windows API Help file. The corresponding parameter on that Help screen is called TextType. The values determine the buttons that appear in the message box and the behavior of the message box. The values can be combined to obtain the desired effect.

The return value of the MessageBox method is 0, if there wasn't enough memory to create the message box, or one of these values:

Value	Numeric value	Meaning

IDABORT	3	The user chose the Abort button.

IDCANCEL	2	The user chose the Cancel button.

IDIGNORE	5	The user chose the Ignore button.

IDNO	7	The user chose the No button.

IDOK	1	The user chose the OK button.

IDRETRY	4	The user chose the Retry button.

IDYES	6	The user chose the Yes button.


TApplication::Minimize

TApplication	See also 	Example

Shrinks an application to the Windows task bar.

void __fastcall Minimize(void);

Description

Call Minimize directly to minimize the application. When the user minimizes the application, the Minimize method is automatically called.

Note:	Don't confuse the Minimize method with minimizing a form or window. To minimize, maximize, or restore a window or form, change the value of the WindowState property.


TApplication::NormalizeAllTopMosts

TApplication	See also

Makes forms, including the Main Window, that have been designated as topmost forms (their FormStyle is fsStayOnTop) behave as if they were not topmost forms.

void __fastcall NormalizeAllTopMosts(void);

Description

NormalizeAllTopMosts behaves like the NormalizeTopMosts method, except that it also includes the Main Window.


TApplication::NormalizeTopMosts

TApplication	See also 	Example

Makes forms that have been designated as topmost forms (their FormStyle is fsStayOnTop) behave as if they were not topmost forms.

void __fastcall NormalizeTopMosts(void);

Description

Use NormalizeTopMosts to have a message box or dialog box that is displayed using the Windows API functions (such as MessageBox and MessageDlg) directly, appear on top of a topmost form. Otherwise the form remains on top, which may obscure the message box.

Calling NormalizeTopMosts is not necessary when using C++Builder methods and functions to display message boxes.

To return the forms designated as fsStayOnTop to be topmost again, call RestoreTopMosts.


TApplication::ProcessMessages

TApplication	See also 	Example

Interrupts the execution of an application so that Windows can respond to events.

void __fastcall ProcessMessages(void);

Description

Call ProcessMessages to permit Windows to process these events at the time ProcessMessages is called. The ProcessMessages method cycles the Windows message loop until it is empty and then returns control to the application.

Note:	Neglecting message processing affects only the application calling ProcessMessages, not other applications. In lengthy operations, calling ProcessMessages periodically will allow the application to respond to paint and other messages.

Note:	ProcessMessages does not allow the application to go idle, whereas HandleMessages does.


TApplication::Restore

TApplication	See also 	Example

Restores a minimized application to its normal size.

void __fastcall Restore(void);

Description

Use Restore to restore the application to its previous size before it was minimized. When the user restores the application to normal size, the Restore method is automatically called.

Note:	Don't confuse the Restore method with restoring a form or window to its original size. To minimize, maximize, and restore a window or form, change the value of the WindowState property.


TApplication::RestoreTopMosts

TApplication	See also 	Example

Restores forms designated as fsStayOnTop to be topmost again.

void __fastcall RestoreTopMosts(void);

Description

Use RestoreTopMosts to return forms that were originally designated as topmost forms (FormStyle is fsStayOnTop), then temporarily changed to be non-topmost forms with the NormalizeTopMosts method, to a topmost position.


TApplication.Run
TApplication::Run

TApplication	See also	Example

Executes the application.

void __fastcall Run(void);

Description

Run contains the application’s main message loop. The call to Run does not return until the application’s message loop is terminated.

When creating a new project, C++Builder automatically creates a main program block in the project file that calls the Run method. When the application is executed, the application’s Run method is called.


TApplication::ShowException

TApplication	See also 	Example

Displays an exception that occurred in an application in a message box.

void __fastcall ShowException(Sysutils::Exception* E);

Description

ShowException is called by HandleException as a default if no handler is specified for the OnException event.

If an exception handler filters exceptions, ShowException will need to be called for those exceptions that are not filtered out.

To specify how exceptions are handled for an application write a handler for the OnException event.

Note:	Calling ShowException is rarely necessary in a C++Builder application, since the default VCL exception handler will call ShowException automatically.


TApplication::Terminate

TApplication	See also 	Example

Ends application execution.

void __fastcall Terminate(void);

Description

Terminate calls the Windows API PostQuitMessage function to perform an orderly shutdown of the application. Terminate is not immediate.

Terminate is called automatically on a WM_QUIT message and when the main form closes.


TApplication::UnhookMainWindow

TApplication	See also

Releases the dialog procedure previously hooked by a call to the HookMainWindow method.

void __fastcall UnhookMainWindow(TWindowHook &Hook);

Description

Use UnhookMainWindow to release the hooked window. Specify the dialog procedure as the value of the Hook parameter.

The TWindowHook type is the parameter type used for the InhookMainWindow method. It is a method-pointer type used for the dialog-procedures of non-C++Builder dialog boxes. The dialog procedure is similar to a window procedure for a window, in that it processes messages for the dialog box, but its syntax is somewhat different.

For more information about Windows hooks see the SetWindowsEx and UnhookWindowsEx functions in the Windows Help File.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent


EArrayError

Hierarchy	Properties	Methods	See also

EArrayError is the exception class for failures that occur when manipulating a descendant of TBaseArray.

Unit

mxarrays

Description

EArrayError is thrown when an application tries to

•	Use an invalid index when accessing the elements of an array.

•	Add too many elements into a fixed-capacity array.

•	Insert an element into a sorted array.


EArrayError properties

EArrayError	Alphabetically

Derived from Exception

HelpContext

Message


EArrayError properties

EArrayError	By object

HelpContext

Message


EArrayError methods

EArrayError	Alphabetically

In EArrayError

~EArrayError

EArrayError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EArrayError methods

EArrayError	By object

~EArrayError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EArrayError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EArrayError::EArrayError

EArrayError	See also

EArrayError creates a new EArrayError object.

__fastcall EArrayError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EArrayError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EArrayError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EArrayError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EArrayError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EArrayError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EArrayError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EArrayError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EArrayError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EArrayError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EArrayError::~EArrayError

EArrayError	See also

~EArrayError frees the memory associated with the EArrayError object.

__fastcall virtual ~EArrayError(void) { }

Description

Do not call ~EArrayError directly. Instead, use the delete keyword on the object, which causes ~EArrayError to be invoked automatically.


Hierarchy

TObject

Exception


EArrayError example

EArrayError


TAutoObject

Hierarchy	Properties	Methods	See also

TAutoObject is a CoClass that supports the IDispatch interface, and that can be used as a base class for OLE Automation servers.

Unit

comobj

Description

TAutoObject is used as a base class for C++Builder ActiveX control classes and provides support for OLE Automation objects. By implementing the IDispatch interface, TAutoObject encapsulates the following functionality:

•	Provides access to properties and methods exposed by an object by calling a method or by accessing a property of a specified DISPinterface, given any necessary parameters.

•	Converts text names of properties and methods (including their arguments) to their corresponding DISPIDs which identify them.

•	Determines whether there is type information available for this disp interface.

•	Retrieves the type information for a specified dispatch interface.

TAutoObject requires a type library because it supports dual interfaces, and because it inherits the IProvideClassInfo interface support which requires a type library. TAutoObject has a class factory. For creating automation objects that are used internally and do not need a class factory, use TAutoIntfObject as a base class.

Implemented methods of IDispatch

GetIDsOfNames, GetTypeInfo, GetTypeInfoCount, and Invoke.


TAutoObject properties

TAutoObject	Alphabetically	Legend

Derived from TComObject

Controller

Factory

RefCount


TAutoObject properties

TAutoObject	By object	Legend

Controller

Factory

RefCount


TAutoObject methods

TAutoObject	Alphabetically

In TAutoObject

~TAutoObject

TAutoObject

Derived from TComObject

Initialize

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TAutoObject methods

TAutoObject	By object

~TAutoObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

Initialize

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

TAutoObject


TAutoObject::TAutoObject

TAutoObject

TAutoObject creates a new TAutoObject object.

__fastcall TAutoObject(void) : Comobj::TTypedComObject() { }


TAutoObject::~TAutoObject

TAutoObject

~TAutoObject frees the memory associated with the TAutoObject object. Do not call ~TAutoObject directly. Instead, use the delete keyword on the object, which causes ~TAutoObject to be invoked automatically.

__fastcall virtual ~TAutoObject(void) { }


Accessibility

Read-only


Hierarchy

TObject

TComObject

TTypedComObject


TAutoObject example

TAutoObject


TAutoObjectFactory

Hierarchy	Properties	Methods

TAutoObjectFactory is the class factory for TAutoObject.

Unit

comobj

Description

TAutoObjectFactory creates instances of the TAutoObject class, and has methods that manage the functionality of all of the instances of the automation objects it creates.

TAutoObjectFactory inherits support for the IClassFactory and IClassFactory2 interfaces.


TAutoObjectFactory properties

TAutoObjectFactory	Alphabetically	Legend

In TAutoObjectFactory

DispIntfEntry

DispTypeInfo

Derived from TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TAutoObjectFactory properties

TAutoObjectFactory	By object	Legend

ClassID

ClassName

ComClass

ComServer

Description

DispIntfEntry

DispTypeInfo

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TAutoObjectFactory::DispIntfEntry

TAutoObjectFactory	See also

DispIntfEntry contains the entry for the dispatch interface implemented by the OLE Automation object created by the factory.

__property System::PInterfaceEntry DispIntfEntry = {read=FDispIntfEntry};

Description

DispIntfEntry is initialized in the constructor. DispIntfEntry returns the entry for a dispatch interface.


TAutoObjectFactory::DispTypeInfo

TAutoObjectFactory

DispTypeInfo returns an ITypeInfo interface reference to the type information for the dispinterface implmented by the OLE Automation object.

__property _di_ITypeInfo DispTypeInfo = {read=FDispTypeInfo};

Description

DispTypeInfo is used to provide type information on the OLE Automation object created by the factory.


TAutoObjectFactory methods

TAutoObjectFactory	Alphabetically

In TAutoObjectFactory

~TAutoObjectFactory

GetIntfEntry

TAutoObjectFactory

Derived from TTypedComObjectFactory

ClassInfo

GetInterfaceTypeInfo

UpdateRegistry

Derived from TComObjectFactory

CreateComObject

RegisterClassObject

Derived from TObject

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TAutoObjectFactory methods

TAutoObjectFactory	By object

~TAutoObjectFactory

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComObject

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetInterfaceTypeInfo

GetIntfEntry

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

SafeCallException

TAutoObjectFactory

UpdateRegistry


TAutoObjectFactory::TAutoObjectFactory

TAutoObjectFactory	See also

TAutoObjectFactory instantiates an instance of a TAutoObjectFactory object.

__fastcall TAutoObjectFactory(TComServerObject* ComServer, System::TMetaClass* AutoClass, const GUID &ClassID, TClassInstancing Instancing);

Description

TAutoObjectFactory allocates memory for a TAutoObjectFactory object, and calls the parent object's constructor, passing it the same parameters. Then it initializes the DispIntfEntry and DispTypeInfo properties, raising an EOleError exception on error. The TAutoObjectFactory sets the ErrorIID property to point to DispIntfEntry.

Class factories should be instantiated in the initialization section of the unit that includes the code for the CoClass they instantiate. Factories are are automatically available when the server is loaded.


TAutoObjectFactory::GetIntfEntry

TAutoObjectFactory	See also

GetIntfEntry returns the entry for a specific interface implemented in a class.

virtual System::PInterfaceEntry __fastcall GetIntfEntry(const GUID &Guid);

Description

GetIntfEntry calls the GetInterfaceEntry method for the CoClass associated with the class factory.

GetIntfEntry returns the entry for the interface, specified by the IID parameter, in the class. GetIntfEntry is used internally. It is rarely called directly.

Note

One use for this method is to describe to OLE how to automatically dispatch calls to a dual-IDispatch interface. An interface type name, such as IUnknown, can be supplied as the IID parameter since the compiler will replace the interface with the associated GUID.


TAutoObjectFactory::~TAutoObjectFactory

TAutoObjectFactory

~TAutoObjectFactory frees the memory associated with the TAutoObjectFactory object. Do not call ~TAutoObjectFactory directly. Instead, use the delete keyword on the object, which causes ~TAutoObjectFactory to be invoked automatically.

__fastcall virtual ~TAutoObjectFactory(void) { }


Accessibility

Read-only


Hierarchy

TObject

TComObjectFactory

TTypedComObjectFactory


TAutoObjectFactory example

TAutoObjectFactory


TAutoIncField

Hierarchy	Properties	Methods	Events	See also

TAutoIncField represents an autoincrement field in a dataset.

Unit

db

Description

Autoincrement fields can hold values in the range -2,147,483,648 to 2,147,483,647, and are used as a counter for the records in the dataset. Each record is given a unique value in an autoincrement field, with each record receiving the next highest integer from that of the previously inserted record. Autoincrement fields are commonly used to provide a unique primary key value for a record.

TAutoIncField does not introduce any new properties, events, or methods beyond those provided by the TIntegerField class. It exists as a separate class to represent the DataType for an autoincrement field.


TAutoIncField properties

TAutoIncField	Alphabetically	Legend

Derived from TIntegerField

AsFloat

AsInteger

AsString

AsVariant

DataSize

MaxValue

MinValue

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TAutoIncField properties

TAutoIncField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMaskPtr

EditMask

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Lookup

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TAutoIncField events

TAutoIncField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TAutoIncField events

TAutoIncField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TAutoIncField methods

TAutoIncField	Alphabetically

In TAutoIncField

~TAutoIncField

TAutoIncField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TAutoIncField methods

TAutoIncField	By object

~TAutoIncField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TAutoIncField

Validate


TAutoIncField::TAutoIncField

TAutoIncField	See also

Creates an instance of TAutoIncField.

__fastcall virtual TAutoIncField(Classes::TComponent* AOwner);

Description

Do not call TAutoIncField directly. Instead, use the new keyword to create a reference to an autoincrement field at runtime. Most applications do not need to create instances of TAutoIncField because the dataset creates these automatically.

After calling the parent object's constructor, TAutoIncField sets the DataType property to ftAutoInc.


TAutoIncField::~TAutoIncField

TAutoIncField

Frees the memory associated with the TAutoIncField object.

__fastcall virtual ~TAutoIncField(void) { }

Description

Do not call ~TAutoIncField directly. Instead, use the delete keyword on the object, which causes ~TAutoIncField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField

TIntegerField


TAutoIntfObject

Hierarchy	Properties	Methods	See also

TAutoIntfObject is a class that supports the IDispatch interface and ISupportErrorInfo interfaces, and that can be used as a base class for internally used objects that implement dispatch interfaces.

Unit

comobj

Description

TAutoIntfObject is used by objects that support dispatch interfaces, but that are only meant to be used internally. By implementing the IDispatch interface, TAutoIntfObject encapsulates the functionality for an automation object.

TAutoIntfObject does not have a class factory, so it can only be instantiated by calling the constructor. Objects that are externally instantiated typically have a class factory so that they can be instantiated in a standard way.

TAutoIntfObject also supports OLE exception handling through its implementation of the ISupportErrorInfo interface.

TAutoIntfObject is similar to TAutoObject in that both classes implement the IDispatch and (directly or indirectly) ISupportErrorInfo interfaces and both require a type library to support dual interfaces. TAutoIntfObject does not have a class factory which distinguishes it from TAutoObject.

Implemented methods of IDispatch

GetIDsOfNames, GetTypeInfo, GetTypeInfoCount, and Invoke.


TAutoIntfObject properties

TAutoIntfObject	Alphabetically	Legend

In TAutoIntfObject

DispIID

DispIntfEntry

DispTypeInfo

Derived from TInterfacedObject

RefCount


TAutoIntfObject properties

TAutoIntfObject	By object	Legend

DispIID

DispIntfEntry

DispTypeInfo

RefCount


TAutoIntfObject::DispIID

TAutoIntfObject

DispIID is the dispatch identifier.

__property GUID DispIID = {read=FDispIID};

Description

DispIID is used for exception handling.


TAutoIntfObject::DispIntfEntry

TAutoIntfObject	See also

DispIntfEntry contains the entry for the dispatch interface implemented by the automation object.

__property System::PInterfaceEntry DispIntfEntry = {read=FDispIntfEntry};

Description

DispIntfEntry is initialized in the constructor. DispIntfEntry returns the entry for a dispatch interface.


TAutoIntfObject::DispTypeInfo

TAutoIntfObject

DispTypeInfo returns an ITypeInfo interface reference to the type information for the dispinterface implmented by the automation object.

__property _di_ITypeInfo DispTypeInfo = {read=FDispTypeInfo};

Description

DispTypeInfo is used to provide type information on the automation object.


TAutoIntfObject methods

TAutoIntfObject	Alphabetically

In TAutoIntfObject

~TAutoIntfObject

SafeCallException

TAutoIntfObject

Derived from TInterfacedObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TAutoIntfObject methods

TAutoIntfObject	By object

~TAutoIntfObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TAutoIntfObject


TAutoIntfObject::TAutoIntfObject

TAutoIntfObject

TAutoIntfObject instantiates an automation interface object.

__fastcall TAutoIntfObject(const _di_ITypeLib TypeLib, const GUID &DispIntf);

Description

Call TAutoIntfObject to instantiate an automation interface object. TAutoIntfObject allocates memory for an automation interface object, verifies that a type library exists, and intializes the DispIntfEntry property.


TAutoIntfObject::SafeCallException

TAutoIntfObject

SafeCallException is used for OLE exception handling.

virtual HRESULT __fastcall SafeCallException(System::TObject* ExceptObject, void * ExceptAddr);

Description

SafeCallException prevents an exception from being raised to escape its scope. Any exceptions raised must also be handled within the method.

The implementation of a safecall method guarantees that no exceptions are raised by enclosing the statement part of the method in an implied try::::::except block.

Note

SafeCallException calls the global routine HandleSafeCallException, which provides a standard way of handling this behavior. Methods of a CoClass that supports OLE exception handling (that implements the ISupportErrorInfo interface) are affected by this function. If those CoClass methods use the safecall calling convention, they are modified to return an HRESULT. Procedures will return an HRESULT, and functions will pass their usual result value as the last (out) parameter, and will return an HRESULT instead. The method is enclosed in a try::::::finally block, afterwhich the HRESULT is returned, and the environment is set up so that the ISupportErrorInfo implementation will work correctly.


TAutoIntfObject::~TAutoIntfObject

TAutoIntfObject

~TAutoIntfObject frees the memory associated with the TAutoIntfObject object. Do not call ~TAutoIntfObject directly. Instead, use the delete keyword on the object, which causes ~TAutoIntfObject to be invoked automatically.

__fastcall virtual ~TAutoIntfObject(void) { }


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject


TAutoIntfObject example

TAutoIntfObject


TActiveXControl

Hierarchy	Properties	Methods	See also

TActiveXControl is an abstract class that provides the functionality to embed a VCL control into an ActiveX Container window.

Unit

axctrls

Description

TActiveXControl defines the core behavior and interfaces required of an ActiveX control and connects that behavior to any VCL control derived from TWinControl.  This allows the control to be embedded in any ActiveX container, including Internet Explorer, Visual Basic, PowerBuilder, Paradox, Borland C++, IntraBuilder, and, of course, C++Builder.

To create a new ActiveX control class, use the ActiveX control wizard.  The steps for building an ActiveX control are covered in depth in the Developer’s Guide.

The TActiveXControl class is derived from TAutoObject, therefore the object resulting is a COM object that supports OLE Automation, a type library, and has a factory.  In addition, TActiveXControl implements the following behaviors:

•	embedding in a container (site)

•	in-place activation

•	persistence

•	events

•	property pages

•	property browsing

TActiveXControl is an abstract class, and so cannot be instantiated.  Instead, you must derive a new class from TActiveXControl to implement an ActiveX control. This derived class is called an implementation class.  An implementation class derived from TActiveXControl normally implements an automation interface as well, to specify the object’s properties and methods.

Ordinarily, you do not create an instance of an implementation class directly.  Instead, you create a factory object in the initialization section of the unit that contains the class declaration.  The factory object will then create the ActiveX control object when asked to by the system.

Interfaces

In addition to the interfaces inherited from TAutoObject, TActiveXControl implements the following interfaces:

IPersistStreamInit	IOleInPlaceActiveObject

IPersistStorage	IViewObject

IOleObject	IViewObject2

IOleControl	IPerPropertyBrowsing

IOleInPlaceObject	ISpecifyPropertyPages

Note

See the DelCtrls demo in ::::\ActiveX\Delctrls for an example of using C++Builder components as ActiveX controls.


TActiveXControl properties

TActiveXControl	Alphabetically	Legend

In TActiveXControl

Control

Derived from TComObject

Controller

Factory

RefCount


TActiveXControl properties

TActiveXControl	By object	Legend

Controller

Control

Factory

RefCount


TActiveXControl::Control

TActiveXControl	See also

The control property is a pointer to the VCL implementation of the ActiveX control.

__property Controls::TWinControl* Control = {read=FControl};

Description

Control is a pointer to the VCL control derived from TWinControl that implements the ActiveX control.


TActiveXControl methods

TActiveXControl	Alphabetically	Legend

In TActiveXControl

~TActiveXControl

DefinePropertyPages

EventSinkChanged

GetPropertyString

GetPropertyStrings

GetPropertyValue

Initialize

InitializeControl

LoadFromStream

ObjQueryInterface

PerformVerb

PropChanged

PropRequestEdit

SaveToStream

TActiveXControl

WndProc

Derived from TComObject

ObjAddRef

ObjRelease

SafeCallException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TActiveXControl methods

TActiveXControl	By object	Legend

~TActiveXControl

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DefinePropertyPages

Dispatch

EventSinkChanged

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetPropertyString

GetPropertyStrings

GetPropertyValue

InheritsFrom

Initialize

InitializeControl

InitInstance

InstanceSize

LoadFromStream

MethodAddress

MethodName

NewInstance

ObjAddRef

ObjQueryInterface

ObjRelease

PerformVerb

PropChanged

PropRequestEdit

SafeCallException

SaveToStream

TActiveXControl

WndProc


TActiveXControl::DefinePropertyPages

TActiveXControl	See also

This method is called when the control is about to show its property pages.

virtual void __fastcall DefinePropertyPages(TDefinePropertyPage &DefinePropertyPage);

Description

If you want your control to show any property pages, override this method and call the DefinePropertyPage callback function once for each property page to be displayed.  If you do not override this method, no property pages will be shown.

DefinePropertyPage takes one parameter, which is the class id of the property page object that should be added to the property dialog.

An ActiveX property page dialog is a tabbed dialog that is used to edit the properties of one or more ActiveX objects.  Each property page is implemented as a COM object, and can be implemented in the same library as the control or in a separate, registered library.

By default the code generated by the expert for an ActiveX control overrides this method with a comment that contains an example of how to use DefinePropertyPage.


TActiveXControl::~TActiveXControl

TActiveXControl	See also

~TActiveXControl destroys an instance of TActiveXControl.

__fastcall virtual ~TActiveXControl(void);

Description

Do not call ~TActiveXControl directly in an application. Instead, call Free. Free verifies that the ActiveX control is not already freed, and only then calls ~TActiveXControl. ~TActiveXControl frees the resources used to turn the Control into an active X control. It does not destroy the object referenced by the Control property.


TActiveXControl::EventSinkChanged

TActiveXControl	See also

This method is called when the control’s container connects a new event sink interface to the object’s events connection point.

virtual void __fastcall EventSinkChanged(const _di_IUnknown EventSink);

Description

Override this method and store a private version of the sink if you want your object to fire events other than the standard events.  The EventSink parameter is the container’s event sink interface.  This interface can be cast to IDispatch or any dispinterface in order to fire events to the container.

This method is also called when the container wishes to change or remove the event sink interface.  If EventSink is NULL, the event sink is being removed or temporarily disabled because the container requested the control not to fire events. The default code generated by the ActiveX control expert will assign the sink to a variable of the type of the out-bound interface of the control.


TActiveXControl::GetPropertyString

TActiveXControl	See also

This method is called when the Object Inspector wants to obtain a user-readable string to represent a property’s current value.  This string is displayed in the Object Inspector next to the property’s name.

virtual bool __fastcall GetPropertyString(int DispID, System::AnsiString &S);

Description

Overriding this method provides the opportunity to display a property’s current value in a human-readable form rather than in its native format.  For example, a font property might be shown as "Arial, 12pt".

ActiveX containers call this method repeatedly, once for each property in the Object Inspector.

The DispID parameter indicates the property requested.  If you want this property to display a special string, set the S parameter to the string value and return true from this method.

Returning false indicates that no special string is needed to display the value.  In this case, the Object Inspector will display the property’s value in a standard way.

The default implementation generated by the ActiveX control expert will automatically look in the type library to handle enumerated types.


TActiveXControl::GetPropertyStrings

TActiveXControl	See also

This method is called when an Object Inspector wants to obtain a list of property values that the user can choose from.

virtual bool __fastcall GetPropertyStrings(int DispID, Classes::TStrings* Strings);

Description

The Object Inspector normally calls this method when the user clicks the drop-down arrow next to a property in the Object Inspector, but before the picklist is displayed, in order to determine the values to place into the picklist.  The Object Inspector displays these values in a dropdown list next to the property’s value in the Object Inspector.

The DispID parameter indicates the property whose value strings are being requested.  If you want the Object Inspector to show a picklist for the property, override this method and call the Strings::AddObject method to add the items to the list.

In the string parameter of Strings::AddObject, provide the text that will appear in the picklist for the entry.

In the object parameter to Strings::AddObject, provide a unique "cookie value".  This cookie value will be passed back to the GetPropertyValue method to identify which item was selected by the user. Although you can choose any unique value for the cookie value, a common convention is to use an integer value (0 for the first picklist item, 1 for the second, and so on).

Returning false indicates that no picklist should be shown for the property specified by DispID.

Returning true indicates that a picklist should be displayed, and the items in the picklist have been added to the Strings object.

This method works in combination with the GetPropertyValue method, which translates the selected string into a Variant value after the user selects an entry in the picklist.  If you implement this method for a property, you should also implement GetPropertyValue.

The default implementation generated by the ActiveX control expert will automatically look in the type library to handle enumerated types.


TActiveXControl::GetPropertyValue

TActiveXControl	See also

This method is called to convert a picklist selection into a Variant value when the user selects a property value from a picklist in the Object Inspector.

virtual void __fastcall GetPropertyValue(int DispID, int Cookie, System::OleVariant &Value);

Description

You should override this method when you have implemented the GetPropertyStrings method to define a picklist.

The DispID parameter identifies the property being modified.  The Cookie parameter identifies the item that was selected by the user.

In your implementation of this method, you should return a Variant value that corresponds to the selected item in the Value parameter.


TActiveXControl::Initialize

TActiveXControl	See also

Creates the class factory and connection object for the TActiveXControl.

virtual void __fastcall Initialize(void);

Description

The Initialize method creates the class factory object, and creates and encapsulates the VCL control.


TActiveXControl::InitializeControl

TActiveXControl	See also

This method is called after the control and the VCL control are fully created.

virtual void __fastcall InitializeControl(void);

Description

Overriding this method provides the opportunity to further initialize an ActiveX object after the VCL control has been created. In particular, you should bind the OLE event-firing methods to the VCL control’s event properties in InitializeControl.


TActiveXControl::LoadFromStream

TActiveXControl	See also

Loads the ActiveX control’s state from the stream.

virtual void __fastcall LoadFromStream(const _di_IStream Stream);

Description

The default implementation of this method loads the stored properties of the VCL control from the stream.

You can override this method to restore any additional data that was saved by the SaveToStream method. To retrieve the extra data, call  the Stream::Read method.  The data you load must match the data that was saved in the SaveToStream method.

If you override this method, be sure to call the inherited method to restore the VCL object’s properties, unless you specifically want to prevent the control’s properties from being restored from the Stream.

If you need a C++Builder stream, you can use a TOleStream which wraps an Ole stream with a C++Builder stream.


TActiveXControl::ObjQueryInterface

TActiveXControl	See also

The ObjQueryInterface method takes an interface ID (the IID parameter) and returns the requested COM interface on the object.

virtual HRESULT __stdcall ObjQueryInterface(const GUID &IID, void *Obj);

Description

The ObjQueryInterface method forwards the call first to the associated TActiveXControl object if it supports the requested interface, otherwise it queries its own interface.


TActiveXControl::PerformVerb

TActiveXControl	See also

This method is called to execute a custom verb.

virtual void __fastcall PerformVerb(int Verb);

Description

Override this method when you have added verbs to the ActiveX object’s factory using the TActiveXControlFactory::AddVerb method.

The Verb paraemeter indicates which verb should be executed.  This number matches the identifier supplied in the factory’s AddVerb method.


TActiveXControl::PropChanged

TActiveXControl

PropChanged generates an OnChanged event.

void __fastcall PropChanged(const System::WideString PropertyName);

Description

Call PropChanged when the property specified by the PropertyName parameter changes. PropChanged generates an OnChanged event using the IPropertyNotifySink interface.


TActiveXControl::PropRequestEdit

TActiveXControl

PropRequestEdit indicates whether a specified property can be changed.

bool __fastcall PropRequestEdit(const System::WideString PropertyName);

Description

Call PropRequestEdit to determine whether the property specified by the PropertyName parameter can be edited. PropRequestEdit uses the IPropertyNotifySink interface to determine whether the property can be changed, and returns true if it can.


TActiveXControl::SaveToStream

TActiveXControl	See also

Saves the ActiveX control’s state to the provided stream.  The default implementation of this method saves all the stored properties of the VCL control to the stream.

virtual void __fastcall SaveToStream(const _di_IStream Stream);

Description

You can override this method to save any additional data required by the control. To save the extra data, call  the Stream::Write  method.  If you do save additional data, override LoadFromStream to make sure the data can be restored correctly.

If you override this method, be sure to call the inherited method to restore the object’s properties, unless you specifically want to prevent them from being saved.


TActiveXControl::WndProc

TActiveXControl	See also

This method hooks the window procedure of the VCL implementation control.  This gives the ActiveX controller object the opportunity to handle messages of interest to ActiveX controls, such as focus change, activation, etc.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

Normally there is no need to override or call this method.  The method is declared protected virtual to allow future extension of the C++Builder ActiveX framework.

This method normally passes the message through to the control’s original message handler, unless the ActiveX container instructs the ActiveX object to filter out the message from the processing stream.


Accessibility

Read-only


TActiveXControl::TActiveXControl

TActiveXControl

TActiveXControl creates a new TActiveXControl object.

__fastcall TActiveXControl(void) : Comobj::TAutoObject()

__fastcall TActiveXControl(_di_IUnknown const Controller) : Comobj:: TAutoObject(Controller)

__fastcall TActiveXControl(Comobj::TComObjectFactory* Factory, _di_IUnknown const Controller) : Comobj::TAutoObject(Factory, Controller) { }

Description


Scope

Protected


Hierarchy

TObject

TComObject

TTypedComObject

TAutoObject


TActiveXControlFactory

Hierarchy	Properties	Methods	See also

TActiveXControlFactory is the factory class for ActiveX control objects.

Unit

axctrls

Description

An ActiveX control is a COM object, which means the module it is implemented in must provide a factory object for the system to be able to create it.  The TActiveXControlFactory class is a factory for ActiveX controls, which are implemented using the TActiveXControl class.

For more information about COM factories, see TComObjectFactory.

To add an ActiveX control factory to your program, create the factory object in the initialization section of the unit that defines the TActiveXControl object.


TActiveXControlFactory properties

TActiveXControlFactory	Alphabetically	Legend

In TActiveXControlFactory

EventIID

EventTypeInfo

MiscStatus

ToolboxBitmapID

WinControlClass

Derived from TAutoObjectFactory

DispIntfEntry

DispTypeInfo

Derived from TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

ProgID


TActiveXControlFactory properties

TActiveXControlFactory	By object	Legend

ClassID

ClassName

ComClass

ComServer

Description

DispIntfEntry

DispTypeInfo

ErrorIID

EventIID

EventTypeInfo

Instancing

MiscStatus

ProgID

ToolboxBitmapID

WinControlClass


TActiveXControlFactory::EventIID

TActiveXControlFactory	See also

EventIID is the GUID for the control’s events interface.

__property GUID EventIID = {read=FEventIID};

Description

EventIID is used internally to create a connection between the control and the events interface.


TActiveXControlFactory::EventTypeInfo

TActiveXControlFactory	See also

EventTypeInfo is the type information object for the object’s events interface.

__property _di_ITypeInfo EventTypeInfo = {read=FEventTypeInfo};

Description

Use this property to obtain type information for the object’s events interface.


TActiveXControlFactory::MiscStatus

TActiveXControlFactory

MiscStatus is a set of status bits that are stored in the registry.

__property int MiscStatus = {read=FMiscStatus, nodefault};

Description

MiscStatus is stored in a registry entry under the CLSID entry for the class. This entry provides information about the OLE server to a container. The entry contains a set of binary flags for which OLE defines specific meanings. This entry is not required.

OLE control containers must recognize and support the following MiscStatus bits:

Status bit	Container	Comments

ACTIVATEWHENVISIBLE	yes	Indicates that the object would like to be activated when it becomes visible, even it isn’t UI-active.

IGNOREACTIVATEWHENVISIBLE	no	Needed for inactive and windowless control support.

INSIDEOUT	no	Indicates that this object would like to be activated inside-out (capable of being in-place active as well as UI-active::) Usually used with embedded compound documents rather than with controls.

INVISIBLEATRUNTIME	yes	Designates a control that should be visible at design-time, but invisible at run-time.

ALWAYSRUN	yes	Indicates that the object always wants to be in the running state and that the default handler should not delay the loading of the object until the last possible moment.

ACTSLIKEBUTTON	no	Indicates that the object has button-like behavior. This allows the container to ask the control to draw itself as the default button or as a normal button.

ACTSLIKELABEL	no	Indicates that the object behaves like a label. This allows the container to handle the control properly when its label gets focus.

NOUIACTIVATE	yes	Indicates that the control has no user interface to activate.

ALIGNABLE	no	Indicates that the control can be aligned by the user.

SIMPLEFRAME	no	Indicates that the control is a simple holder for other controls.

SETCLIENTSITEFIRST	no	Indicates that the control needs to access the client site very early in its creation.

IMEMODE	no	Indicates that the control supports Input Method Identifiers (IMEs) to create extended characters. Typically, a container that supports IME will provide the control with an extended IMEMode property.


TActiveXControlFactory::ToolboxBitmapID

TActiveXControlFactory	See also

ToolboxBitmapID is the resource identifier of the ActiveX control.

__property int ToolboxBitmapID = {read=FToolboxBitmapID, nodefault};

Description

Use ToolboxBitmapID to obtain the resource ID of the bitmap that is used to represent the control on a design palette.


TActiveXControlFactory::WinControlClass

TActiveXControlFactory	See also

WinControlClass is the class of the VCL control that implements the Windows behavior for the ActiveX control.

__property System::TMetaClass* WinControlClass = {read=FWinControlClass};

Description

The factory object keeps a reference to the VCL control’s class information so that it can ask the class object to manufacture a VCL control when the ActiveX control is created.


TActiveXControlFactory methods

TActiveXControlFactory	Alphabetically

In TActiveXControlFactory

~TActiveXControlFactory

AddVerb

TActiveXControlFactory

UpdateRegistry

Derived from TTypedComObjectFactory

ClassInfo

GetInterfaceTypeInfo

Derived from TComObjectFactory

CreateComObject

RegisterClassObject

Derived from TObject

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TActiveXControlFactory methods

TActiveXControlFactory	By object

~TActiveXControlFactory

AddVerb

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComObject

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetInterfaceTypeInfo

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

TActiveXControlFactory

UpdateRegistry


TActiveXControlFactory::AddVerb

TActiveXControlFactory	See also

AddVerb adds a verb to the object’s list of supported verbs.

void __fastcall AddVerb(int Verb, const System::AnsiString VerbName);

Description

Use AddVerb to add a verb that host applications can apply to the ActiveX control.  In the Verb parameter, pass a number to identify the verb.  User-defined verbs are normally small positive numbers.

In the VerbName parameter, pass the text to display when presenting the user with a choice of verbs.  In some OLE containers, the verb text is displayed in a popup menu when the user right-clicks on a control.

Placing an ampersand (&) before a character in this string causes the character to be displayed underlined in a pop-up menu.

OLE defines the following commonly used verbs:

VerbName	Verb

OLEIVERB_PRIMARY	0

OLEIVERB_SHOW	–1

OLEIVERB_OPEN	–2

OLEIVERB_HIDE	–3

OLEIVERB_UIACTIVATE	–4

OLEIVERB_INPLACEACTIVATE	–5

OLEIVERB_DISCARDUNDOSTATE	–6

OLEIVERB_PROPERTIES	–7


TActiveXControlFactory::TActiveXControlFactory

TActiveXControlFactory	See also

TActiveXControlFactory creates and initializes a new TActiveXControlFactory object.

__fastcall TActiveXControlFactory(Comobj::TComServerObject* ComServer, System::TMetaClass* ActiveXControlClass, System::TMetaClass* WinControlClass, const GUID &ClassID, int ToolboxBitmapID, const System::AnsiStringLicStr, int MiscStatus);

Description

The ComServer parameter is a pointer to the COM server object for the module containing the property page factory. This is normally a global variable, ComServer, declared in the ComServ unit.

The ActiveXControlClass parameter is the class object for the controller object that implements the ActiveX control. This object should be derived from TActiveXControl.

The WinControlClass parameter is the class object for the VCL control class that implements the Windows behavior of the control. This object should be derived from TWinControl.

The ClassID parameter is the GUID of the ActiveX control. Each COM object should have a unique GUID.  See the for more on how to make a GUID.

LicStr is the license string for controls created with this factory. LicStr is empty if controls created with this factory are unlicensed. MiscStatus are the status bits that are stored in the registry.


TActiveXControlFactory::~TActiveXControlFactory

TActiveXControlFactory	See also

Description

__fastcall virtual ~TActiveXControlFactory(void);

Do not call ~TActiveXControlFactory directly in an application.  Instead, call Free.  Free verifies that the TActiveXControlFactory object is not already freed and only then calls ~TActiveXControlFactory.


TActiveXControlFactory::UpdateRegistry

TActiveXControlFactory	See also

UpdateRegistry adds or removes registry entries for the object.

virtual void __fastcall UpdateRegistry(bool Register);

Description

This method is called to add or remove the control from the system registry.  The default behavior of this method is to add normal ActiveX control registry keys, server file information, and type library information to the registry.  It also adds the verbs added with the AddVerb method.

If the Register parameter is true, the control should add its keys to the system registry.  If it is false, the control should remove its keys from the registry.

Override this method if you want your control to store more information in the registry than the base implementation stores.  If you do override this method, be sure to call the inherited implementation in the correct order.  When adding registry entries (that is, Register is true), call the inherited method before adding custom entries.  When removing registry entries (that is, Register is false), call the inherited method after removing the custom entries.


Accessibility

Read-only


Hierarchy

TObject

TComObjectFactory

TTypedComObjectFactory

TAutoObjectFactory


TActiveXPropertyPageFactory

Hierarchy	Properties	Methods	See also

TActiveXPropertyPageFactory implements a COM factory for an ActiveX property page.

Unit

axctrls

Description

A property page is a COM object, which means the module it is implemented in must provide a factory so that the system can create the object. TActiveXPropertyPageFactory is a factory for ActiveX property pages, which are implemented by subclassing TPropertyPage.

For more information about COM factories, see TComObjectFactory.

To add a property page factory to a program, create the factory object in the initialization section of the unit that defines the property page form.


TActiveXPropertyPageFactory properties

TActiveXPropertyPageFactory	Alphabetically	Legend

Derived from TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

ProgID


TActiveXPropertyPageFactory properties

TActiveXPropertyPageFactory	By object	Legend

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

ProgID


TActiveXPropertyPageFactory methods

TActiveXPropertyPageFactory	Alphabetically

In TActiveXPropertyPageFactory

~TActiveXPropertyPageFactory

TActiveXPropertyPageFactory

Derived from TComObjectFactory

RegisterClassObject

UpdateRegistry

Derived from TObject

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TActiveXPropertyPageFactory methods

TActiveXPropertyPageFactory	By object

~TActiveXPropertyPageFactory

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

SafeCallException

TActiveXPropertyPageFactory

UpdateRegistry


TActiveXPropertyPageFactory::TActiveXPropertyPageFactory

TActiveXPropertyPageFactory	See also

Creates a property page factory and binds that factory to property page class.

Description

The ComServer parameter is a pointer to the COM server object for the ActiveX library.  This is normally the global variable, ComServer, declared in the ComServ unit.

The PropertyPageClass parameter is the class object of the property page’s implementing class.  The implementing class must be derived form TPropertyPage.  This class implements the form that is to appear in the property dialog.

The ClassID parameter is a GUID that identifies the property page’s class.  Each property page should have its own GUID.  See the Programmer’s Guide for information on how to create a GUID.


TActiveXPropertyPageFactory::~TActiveXPropertyPageFactory

TActiveXPropertyPageFactory

~TActiveXPropertyPageFactory frees the memory associated with the TActiveXPropertyPageFactory object. Do not call ~TActiveXPropertyPageFactory directly. Instead, use the delete keyword on the object, which causes ~TActiveXPropertyPageFactory to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TComObjectFactory


TActiveXPropertyPageFactory example

TActiveXPropertyPageFactory


TActiveXPropertyPage

Hierarchy	Properties	Methods	See also

The TActiveXPropertyPage object is a COM object that provides the interfaces necessary to support an ActiveX property page.

Unit

axctrls

Description

This class is used internally by the TPropertyPage control to provide a bridge between a C++Builder form and the ActiveX property page API.


TActiveXPropertyPage properties

TActiveXPropertyPage	Alphabetically	Legend

Derived from TComObject

Controller

Factory

RefCount


TActiveXPropertyPage properties

TActiveXPropertyPage	By object	Legend

Controller

Factory

RefCount


TActiveXPropertyPage methods

TActiveXPropertyPage	Alphabetically

In TActiveXPropertyPage

~TActiveXPropertyPage

Initialize

TActiveXPropertyPage

Derived from TComObject

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TActiveXPropertyPage methods

TActiveXPropertyPage	By object

~TActiveXPropertyPage

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

Initialize

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

TActiveXPropertyPage


TActiveXPropertyPage::~TActiveXPropertyPage

TActiveXPropertyPage	See also

Frees the instance of the TPropertyPage.

Description

Don’t call ~TActiveXPropertyPage directly in an application.  Instead, call Free. Free verifies that the TPropertyPage object is not already freed and only then calls ~TActiveXPropertyPage::.


TActiveXPropertyPage::Initialize

TActiveXPropertyPage 	See also

Initializes the instance of a TPropertyPage descendant.

Description

Override the Initialize method to initialize an instance of a TPropertyPage descendant before it is used.


TActiveXPropertyPage::TActiveXPropertyPage

TActiveXPropertyPage

TActiveXPropertyPage creates a new TActiveXPropertyPage object.


Accessibility

Read-only


Hierarchy

TObject

TComObject


TBaseArray

Hierarchy	Properties	Methods	See also

TBaseArray is the base class for all arrays used by the decision cube components.

Unit

mxarrays

Description

Use TBaseArray as a base class when defining a specialized array for a specific data type. Like the TList or TStringList object, TBaseArray represents an ordered list of items that can grow dynamically. However, the elements of TBaseArray are arbitrary types whose size is specified in the constructor, while TStringList is limited to strings and TList is limited to pointers.

Descendants of TBaseArray represent arrays of specific data types such as short integers.


TBaseArray properties

TBaseArray	Alphabetically	Legend

In TBaseArray

AutoSize

Capacity

CompareProc

Count

Duplicates

ItemSize

Limit

List

SortOrder


TBaseArray properties

TBaseArray	By object	Legend

AutoSize

Capacity

CompareProc

Count

Duplicates

ItemSize

Limit

List

SortOrder


TBaseArray::AutoSize

TBaseArray	See also

Indicates whether the array grows dynamically as items are added.

__property bool AutoSize = {read=GetAutoSize, write=SetAutoSize, nodefault};

Description

Set AutoSize to true to allow the array to hold an arbitrary number of values. When AutoSize is true, the Capacity property increases automatically when new items are added beyond the current capacity of the array. When AutoSize is false, the Capacity property must be explicitly set to the number of entries allowed in the array. If an attempt is made to add items beyond the number specified in the Capacity property, an EArrayError exception is thrown if AutoSize is false.


TBaseArray::Capacity

TBaseArray	See also

Specifies the maximum number of items that can be added to the array.

__property int Capacity = {read=FCapacity, write=SetCapacity, nodefault};

Description

Set Capacity to change the amount of memory allocated for the array. Trying to set Capacity to a value less than the Count property will throw an EArrayError exception.

If the AutoSize property is true, the Capacity of the array increases automatically when necessary to accommodate new items as they are added.

Note:	To determine the amount of memory used by the array, use Capacity * ItemSize.


TBaseArray::CompareProc

TBaseArray	See also

Implements a sort order for the elements of the array.

typedef int __fastcall (*TCompareProc)(void *item1, void *item2);

__property TCompareProc CompareProc = {read=FCompProc, write=FCompProc};

Description

Set CompareProc to change the function that is used to sort the items of the array. If the SortOrder property is not TS_NONE, CompareProc is used to locate the position in which to add new items to the array and to locate items using the FindItem method.

CompareProc should compare the two items given as parameters and return a value less than 0 if item1 comes before item2, return a value greater than 0 if item1 comes after item2, and return 0 if item1 is the same as item2.


TBaseArray::Count

TBaseArray	See also

Indicates the number of items in the array.

__property int Count = {read=FCount, write=SetCount, nodefault};

Description

Read Count to determine the number of entries in the array. Set Count to increase or decrease the number of entries. Increasing Count always increases the Capacity if necessary, even if the AutoSize property is false. Decreasing the Count property truncates the array after Count items, but does not affect the Capacity of the array.

When the value of Count is increased, new entries with the value of 0 are added to the end of the array. If the array is sorted, this will throw off the internal sort order, and cause the FindItem method to fail. If the array is sorted, call the Sort method to restore the sort order after filling the newly added members of the array.


TBaseArray::Duplicates

TBaseArray	See also

Specifies whether duplicate items can be added to sorted arrays.

enum TDuplicates { dupIgnore, dupAccept, dupError };

__property TDuplicates Duplicates = {read=FDuplicates, write=FDuplicates, nodefault};

Description

Set Duplicates to specify what should happen when an attempt is made to add a duplicate item to a sorted array. The value of Duplicates should be one of the following.

Value	Meaning

dupIgnore	Ignore attempts to add duplicate items to the sorted array.

dupError	Throw an EArrayError exception when an attempt is made to add duplicate items to the sorted array.

dupAccept	Permit duplicate items in the sorted array.

Set Duplicates before adding any items to the list. Setting Duplicates to dupIgnore or dupError does nothing about duplicate strings that are already in the array.

Note:	Duplicates does nothing if the array is not sorted.


TBaseArray::ItemSize

TBaseArray	See also

Indicates the number of bytes used to store each item in the array.

__property int ItemSize = {read=FItemSize, nodefault};

Description

Read ItemSize to determine the size of the elements of the array. The value of ItemSize is set by the constructor to the value of its iSize parameter. Descendants of TBaseArray change this value to the size of the data type they represent.


TBaseArray::Limit

TBaseArray	See also

Specifies the size of the array.

__property int Limit = {read=GetLimit, write=SetCapacity, nodefault};

Description

Use Limit to determine the size of the array. If the array is empty, Limit is the same as the Capacity property. If the array is not empty, Limit is the same as the Count property, even if the value of Capacity is larger than Count. Setting Limit sets the Capacity of the array.


TBaseArray::List

TBaseArray	See also

Points to the array of values maintained by TBaseArray.

__property void * List = {read=FMemory};

Description

Use List to get direct access to the memory used to store the array items. Calculate the position of individual items in the list using the ItemSize property.

To access specific items in the list, use the GetItem method.


TBaseArray::SortOrder

TBaseArray	See also

Determines whether the array is sorted.

enum TSortOrder { TS_NONE, TS_ASCENDING, TS_DESCENDING };

__property TSortOrder SortOrder = {read=FSortOrder, write=FSortOrder, nodefault};

Description

Set SortOrder to indicate whether the array should be sorted using the CompareProc property. When an array is sorted, all new items are added in the correct sort-order position so as to maintain the sort order. SortOrder can have one of the following values:

Value	Meaning

TS_NONE	The array is unsorted.

TS_ASCENDING	The elements of the array are sorted in ascending order.

TS_DESCENDING	The elements of the array are sorted in descending order.

Setting the SortOrder property does not sort the items already in the array. If the array is not empty when the SortOrder property is changed to TS_ASCENDING or TS_DESCENDING, be sure to explicitly call the Sort method to sort the existing items.

Note:	The Duplicates property has no effect when SortOrder is TS_NONE.


TBaseArray methods

TBaseArray	Alphabetically

In TBaseArray

~TBaseArray

Clear

Delete

Exchange

FindItem

GetItem

IndexOf

Insert

InsertAt

PutItem

RemoveItem

Sort

TBaseArray

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBaseArray methods

TBaseArray	By object

~TBaseArray

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

Exchange

FieldAddress

FindItem

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetItem

GetNamePath

IndexOf

InheritsFrom

InitInstance

Insert

InsertAt

InstanceSize

MethodAddress

MethodName

NewInstance

PutItem

RemoveItem

SafeCallException

Sort

TBaseArray


TBaseArray::Clear

TBaseArray	See also

Removes all items from the array.

void __fastcall Clear(void);

Description

Call Clear to empty the array and free all associated memory. Clear does the same thing as setting both the Count and Capacity properties to 0.


TBaseArray::TBaseArray

TBaseArray	See also

Creates an instance of TBaseArray for elements of a specific size.

__fastcall virtual TBaseArray(int itemcount, int iSize);

Description

Do not create instances of TBaseArray. Instead, create a descendant of TBaseArray defined for a particular type of data.

TBaseArray sets the Capacity property to Itemcount and the ItemSize property to iSize. It also initializes the AutoSize property to true and the Count property to 0.


TBaseArray::Delete

TBaseArray	See also

Removes an element from the array.

virtual void __fastcall Delete(int Index);

Description

Call Delete to remove the element indicated by the Index parameter, where 0 is the first element, 1 is the second element, and so on. All subsequent elements in the array are moved up to fill the gap left when the element is removed.


TBaseArray::~TBaseArray

TBaseArray	See also

Destroys an instance of TBaseArray.

__fastcall virtual ~TBaseArray(void);

Description

Do not call ~TBaseArray directly in an application. Instead, use the delete keyword.

~TBaseArray frees the memory allocated to hold the list of elements before calling the parent object's destructor.


TBaseArray::Exchange

TBaseArray	See also

Provides the interface for a method that swaps the values of two elements in the array.

virtual void __fastcall Exchange(int Index1, int Index2);

Description

The Exchange method for TBaseArray does nothing other than provide an interface for a method that interchanges the values of two elements.


TBaseArray::FindItem

TBaseArray	See also

Locates a value in a sorted array and indicates whether an element with that value already exists.

bool __fastcall FindItem(int &Index, void *Value);

Description

Use FindItem to obtain the index in a sorted array where an element with the value Value should be added. If an element with the value Value already exists in the array, FindItem returns true. If none of the elements in the array have the value Value, FindItem returns false.

The index where Value should appear is returned in the Index parameter. The value of Index is zero-based, where the first element has the index 0, the second element has the index 1, and so on.

Note:	FindItem assumes the SortOrder property is TS_ASCENDING. For unsorted arrays, use the IndexOf method instead. For descending arrays, invert the CompareProc property before calling FindItem.


TBaseArray::GetItem

TBaseArray	See also

Returns the element in the array at the indicated position.

void __fastcall GetItem(int index, void *Value);

Description

Call GetItem to obtain the value of an element in the array. The Index parameter indicates the element of the array, where the first element has the index 0, the second element has the index 1, and so on.


TBaseArray::IndexOf

TBaseArray	See also

Returns the position of the first element with a specified value.

virtual int __fastcall IndexOf(void *Item);

Description

Call IndexOf to obtain the position of the first occurrence of the value Value. IndexOf returns the 0-based index of the element. Thus, if Value matches the first element in the array, IndexOf returns 0, if Value matches the second element, IndexOf returns 1, and so on. If the value is not in the array, IndexOf returns -1.

Note:	IndexOf does not work for arrays sorted in descending order.


TBaseArray::Insert

TBaseArray	See also

Inserts an element into the array and assigns it a value.

virtual void __fastcall Insert(int Index, void *Value);

Description

Call InsertAt to add an element to the array at the position specified by Index and assign it the value Value. If Index is 0, the element is inserted at the beginning of the array. If Index is 1, the element is put in the second position of the array, and so on.

Note:	Insert does not check the SortOrder property. If the array is sorted, be sure to insert the element in the proper sort-order position.


TBaseArray::InsertAt

TBaseArray	See also

Adds an element to the array at the position specified by Index.

void __fastcall InsertAt(int Index, void *Value);

Description

InsertAt does the same thing as the Insert method. For most purposes, use the Insert method.

Descendants of TBaseArray can override the Insert method to throw an exception when an attempt is made to insert an element in a sorted array. InsertAt always succeeds as long as the value of Index is appropriate. InsertAt is intended for internal use when the value of Index is known to be appropriate.


TBaseArray::PutItem

TBaseArray	See also

Replaces the value of an element in the array.

void __fastcall PutItem(int index, void *Value);

Description

Call PutItem to change the value of an element to the value Value. Unlike the Insert method, PutItem does not add a new item to the array, but replaces the value of an existing element. The Index parameter indicates which element to change, where 0 specifies the first element, 1 specifies the second element, and so on.

Note:	Calling PutItem with Index set to the value of the Count property will add a new element to the end of the array. This is the only case where PutItem adds a new element instead of replacing an existing one.


TBaseArray::RemoveItem

TBaseArray	See also

Removes an element from the array.

void __fastcall RemoveItem(int Index);

Description

RemoveItem does the same thing as the Delete method. Use the Delete method instead.


TBaseArray::Sort

TBaseArray	See also

Provides the interface for a method that sorts the elements in the array.

typedef int __fastcall (*TCompareProc)(void *item1, void *item2);

virtual void __fastcall Sort(TCompareProc Compare);

Description

The Sort method for TBaseArray does nothing. Descendants of TBaseArray override this method to sort the elements of the array using the ordering function provided in the Compare parameter.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


 TBatchMove

Hierarchy	Properties	Methods	See also

TBatchMove enables applications to perform database operations on groups of records or entire tables.

Unit

dbtables

Description

Instantiate a TBatchMove object to

•	Add the records in a dataset to a database table.

•	Delete the records in a dataset from a database table.

•	Copy a dataset to create a new database table or overwrite an existing table.

Set the properties of the TBatchMove object to specify the desired operation. Call the Execute method to perform the actual operation. TTable objects can also perform the same batch operations, but only with the options specified by the default TBatchMove property values.

TBatchMove has several properties that instruct the Borland Database Engine (BDE) how to handle problems that occur when executing the batch operation. Additionally, applications can use a TBDECallback object to further refine the response to problems that arise.


TBatchMove properties

TBatchMove	Alphabetically	Legend

In TBatchMove

AbortOnKeyViol

AbortOnProblem

ChangedCount

ChangedTableName

CommitCount

Destination

KeyViolCount

KeyViolTableName

Mappings

Mode

MovedCount

ProblemCount

ProblemTableName

RecordCount

Source

Transliterate

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TBatchMove properties

TBatchMove	By object	Legend

AbortOnKeyViol

AbortOnProblem

ChangedCount

ChangedTableName

CommitCount

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

DesignInfo

Destination

KeyViolCount

KeyViolTableName

Mappings

Mode

MovedCount

Name

Owner

ProblemCount

ProblemTableName

RecordCount

Source

Tag

Transliterate

VCLComObject


TBatchMove::AbortOnKeyViol

TBatchMove	See also

Specifies whether the batch operation is terminated immediately when integrity or key violations occur.

__property bool AbortOnKeyViol = {read=FAbortOnKeyViol, write=FAbortOnKeyViol, default=1};

Description

Set AbortOnKeyViol to true to cancel the batch operation when it causes integrity or key violations in the destination table. Set AbortOnKeyViol to false to cause records that would cause integrity or key violations to be posted to a key violations table instead. Provide a KeyViolTableName when setting AbortOnKeyViol to false. If there is no KeyViolTableName, AbortOnKeyViol may still be set to false, in which case problem records are counted but not saved in a table.

Key violations occur when appending records to a table that has a primary key. On a table with a primary key, no two records may have the same values on all of the key fields. If a record that is being appended has the same values on all the key fields as a record in the destination table, it cannot be appended.

Integrity violations occur when deleting, appending or updating records to a table that has a referential integrity specification. A referential integrity specification requires that certain fields in one table must have values that exist in a particular field of another table. If a record that is being added does not match the restrictions imposed by referential integrity, it cannot be added. If deleting record would cause tighter referential integrity restrictions that another table cannot meet, it cannot be deleted.


TBatchMove::AbortOnProblem

TBatchMove	See also

Specifies whether the batch operation is terminated immediately when it is necessary to truncate data to make it fit in the specified Destination.

__property bool AbortOnProblem = {read=FAbortOnProblem, write=FAbortOnProblem, default=1};

Description

Set AbortOnProblem to true to cancel the batch operation when types of the fields in the Source table records do not match the types of the fields in the Destination table records. Set AbortOnProblem to false to cause the mismatched fields to be “trimmed”. When AbortOnProblem is false, set the ProblemTableName to have all the untrimmed versions of records that were trimmed saved to a separate table.

Trimming a field means converting its value to a value compatible with the destination field type. For example, if a field in the destination table holds a string of size 10 characters, and the corresponding field in the source table holds a string of size 15 characters, any values from the source table longer than 10 characters must be truncated. Values that cannot be converted will cause TBatchMove to throw an exception.

Trimming does not occur when the Mode property is set to batCopy. Trimming fields on a delete operation means that records in the destination table may be deleted that do not exactly match the values from the source table.

Note:	To allow trimming on a field by field basis, use a TBDECallback object.


TBatchMove::ChangedCount

TBatchMove	See also

Indicates the number of records from the Destination table altered as a result of the batch operation.

__property int ChangedCount = {read=FChangedCount, nodefault};

Description

Use ChangedCount to learn the number of records in the Destination table that are updated if the Mode is batUpdate or batAppendUpdate, or to learn the number that are deleted if the Mode is batDelete.

Set the ChangedTableName property to save the unchanged versions of the altered records to a separate table. ChangedCount is then the number of records in that separate table.


TBatchMove::ChangedTableName

TBatchMove	See also

Specifies the name of a local Paradox table that is created to hold copies of all records from the destination table that are changed by the batch operation.

__property System::AnsiString ChangedTableName = {read=FChangedTableName, write=FChangedTableName};

Description

Set ChangedTableName to create a table that saves all unchanged versions of records that are changed by the batch operation. ChangedTableName must specify the name of a Paradox table. Setting ChangedTableName ensures that no information in the Destination table gets lost when the records are altered or deleted.

When the Mode property is batUpdate or batAppendUpdate, the new table will hold all records that were updated. When the Mode property is batDelete, the new table will hold all records that were deleted.

The ChangedCount property specifies the number of records in the new table.


TBatchMove::CommitCount

TBatchMove	See also

Specifies how many records are batch moved before a commit occurs.

__property int CommitCount = {read=FCommitCount, write=FCommitCount, default=0};

Description

Use CommitCount to chunk batch operations into smaller operations. CommitCount allows an application to accommodate server transaction logs that are not big enough to handle the entire batch. Setting CommitCount to 0 will cause chunking into the number of records that will fit in 32K bytes.

Note:	If the Execute method is called within an explicit transaction on the database containing the tables, CommitCount is ignored.


TBatchMove::Destination

TBatchMove	See also

Specifies the TTable object for the database table that is the destination of the batch operation.

__property TTable* Destination = {read=FDestination, write=FDestination};

Description

Use Destination to indicate the database table that will be created or altered by the batch operation. The batch operation affects the Destination differently depending on the Mode:

Mode	Effect on Destination

batAppend	Records are added to the destination table. No pre-existing records are altered. Destination table must already exist.

batUpdate	Records in the destination table with key fields matching the corresponding fields in the source are changed to match the source records. No new records are added. Destination table must already exist and must have an index defined.

batAppendUpdate	Records in the destination table with key fields matching the corresponding fields in the source are changed to match the source. Source records that do not match key fields are added to the destination table. Destination table must already exist and must have an index defined.

batDelete	Records in the destination table that match the records in the source are deleted. Destination table must already exist and must have an index defined.

batCopy	Destination table is created to match the records in the source. If Destination already exists, it is replaced by the copy of the source.


TBatchMove::KeyViolCount

TBatchMove	See also 	Example

Reports the number of records which could not be replaced, added, or deleted from Destination because of integrity or key violations.

__property int KeyViolCount = {read=FKeyViolCount, nodefault};

Description

Use KeyViolCount to learn the number of records form the Source table that could not be applied to the Destination table because of integrity or key violations. To obtain a table of the offending records from the Source table, specify a KeyViolTableName.

Key violations occur when appending records to a table that has a primary key. On a table with a primary key, no two records may have the same values on all of the key fields. If a record that is being appended has the same values on all the key fields as a record in the destination table, it cannot be appended.

Integrity violations occur when deleting, appending or updating records to a table that has a referential integrity specification. A referential integrity specification requires that certain fields in one table must have values that exist in a particular field of another table. If a record that is being added does not match the restrictions imposed by referential integrity, it cannot be added. If deleting record would cause tighter referential integrity restrictions that another table cannot meet, it cannot be deleted.

Note:	If AbortOnKeyViol is true, KeyViolCount will never be greater than one, because the first violation will cause the batch operation to terminate.


TBatchMove::KeyViolTableName

TBatchMove	See also

Specifies the name of a Paradox table that will be created to contain all records from the Source that cannot participate in the batch operation because of integrity or key violations.

__property System::AnsiString KeyViolTableName = {read=FKeyViolTableName, write=FKeyViolTableName};

Description

Use KeyViolTableName to obtain a table of records that could not be applied to the Destination table because of integrity or key violations. KeyViolCount has the number of records in the table that is created.

Key violations occur when appending records to a table that has a primary key. On a table with a primary key, no two records may have the same values on all of the key fields. If a record that is being appended has the same values on all the key fields as a record in the destination table, it cannot be appended.

Integrity violations occur when deleting, appending or updating records to a table that has a referential integrity specification. A referential integrity specification requires that certain fields in one table must have values that exist in a particular field of another table. If a record that is being added does not match the restrictions imposed by referential integrity, it cannot be added. If deleting record would cause tighter referential integrity restrictions that another table cannot meet, it cannot be deleted.

Note:	If AbortOnKeyViol is true, then there will be at most one record in this table because the operation aborts with that first record.


TBatchMove::Mappings

TBatchMove	See also 	Example

Specifies the column mappings for a batch operation.

__property Classes::TStrings* Mappings = {read=FMappings, write=SetMappings};

Description

Set Mappings to specify the correspondence between fields in the Source and fields in the Destination. By default TBatchMove matches fields based on their position in the source and destination tables. That is, the first column in the source is matched with the first column in the destination, and so on. Mappings enables an application to override this default.

Mappings is a list of column mappings (one per line) in one of two forms. To map the column ColName in the source table to the column of the same name in the destination table, use:

To map the column named SourceColName in the source table to the column named DestColName in the destination table, use:

When adding or appending records, fields in Destination which have no entry in Mappings will be set to NULL. When copying a dataset, fields in Destination which have no entry in Mappings will not appear as columns in the copy of the table.

If source and destination column data types are not the same, TBatchMove can either cancel the batch operation or perform a “best fit”. If AbortOnProblem is true, type mismatches will terminate the batch move. Otherwise, the field values from the Source will be converted, if possible, to be compatible with the Destination.


TBatchMove::Mode

TBatchMove	See also 	Example

Specifies what the TBatchMove object does when the Execute method is called.

__property TBatchMode Mode = {read=FMode, write=FMode, default=0};

Description

Use Mode to indicate whether the TBatchMove object should add records, replace records, delete records, or copy the Source. These are the possible values for Mode:

Value	Meaning

batAppend	Append the records in the source to the destination table. The destination table must already exist, and the two tables must not have records with duplicate keys. This is the default mode.

batUpdate	Replace records in the destination table with matching records from the source table. The destination table must exist and must have an index defined to match records.

batAppendUpdate	If a matching record exists in the destination table, replace it. Otherwise, append records to the destination table. The destination table must exist and must have an index defined to match records.

batCopy	Create the destination table based on the structure of the source table. If the destination already exists, the operation will delete it, and replace it with the new copy of the source.

batDelete	Delete records in the destination table that match records in the source table. The destination table must already exist and must have an index defined.


TBatchMove::MovedCount

TBatchMove	See also 	Example

Reports the number of records form the Source which were applied to the destination.

__property int MovedCount = {read=FMovedCount, nodefault};

Description

Read MovedCount to learn the number of records from the Source that were read during the Execute method. The MovedCount value includes any records which caused key or integrity violations, or which were trimmed.


TBatchMove::ProblemCount

TBatchMove	See also

Indicates the number of records which could not be added to Destination without loss of data due to a field type mismatch.

__property int ProblemCount = {read=FProblemCount, nodefault};

Description

Read ProblemCount to learn the number of records from the Source that had field values which could not be mapped to destination fields without being “trimmed”. If a ProblemTableName is specified, ProblemCount is the number of records in that table.

Trimming a field means converting its value to a value compatible with the destination field type. For example, if a field in the destination table holds a string of size 10 characters, and the corresponding field in the source table holds a string of size 15 characters, any values from the source table longer than 10 characters must be truncated. Values that cannot be converted will cause TBatchMove to throw an exception.

Trimming does not occur when the Mode property is set to batCopy. Trimming fields on a delete operation means that records in the destination table may be deleted that do not exactly match the values from the source table.

Note:	If AbortOnProblem is true, then ProblemCount will be at most one, because the operation aborts when the problem occurs.


TBatchMove::ProblemTableName

TBatchMove	See also

Specifies the name of a Paradox table that will be created to contain all records from the Source that contain fields which were trimmed to match the corresponding field type in the Destination table.

__property System::AnsiString ProblemTableName = {read=FProblemTableName, write=FProblemTableName};

Description

Set ProblemTableName to create a table that holds records from the Source that contain fields that had to be trimmed to be applied to the Destination. ProblemCount will have the number of records placed in the new table. If ProblemTableName is not specified, the data in the record is still trimmed when applied to the destination table, but there will be no easy way to tell which fields were trimmed.

Trimming a field means converting its value to a value compatible with the destination field type. For example, if a field in the destination table holds a string of size 10 characters, and the corresponding field in the source table holds a string of size 15 characters, any values from the source table longer than 10 characters must be truncated. Values that cannot be converted will cause TBatchMove to throw an exception.

Trimming does not occur when the Mode property is set to batCopy. Trimming fields on a delete operation means that records in the destination table may be deleted that do not exactly match the values from the source table.

Note:	If AbortOnProblem is true, then there will be at most one record in this table because the operation aborts with the first record that has a problem.


TBatchMove::RecordCount

TBatchMove	See also

Specifies the maximum number of records that are applied to the Destination when Execute is called.

__property int RecordCount = {read=FRecordCount, write=FRecordCount, default=0};

Description

Use RecordCount to limit the number of Source records that are applied to the Destination. If zero, all records are added, subtracted, or copied, beginning with the first record in Source. If RecordCount is greater than zero, up to RecordCount records are applied to the Destination, starting with the current record in the dataset. If RecordCount exceeds the number of records remaining in Source, no wraparound occurs; the operation is terminated.


TBatchMove::Source

TBatchMove	See also

Specifies the dataset that is the source of the batch operation.

__property TBDEDataSet* Source = {read=FSource, write=SetSource};

Description

Use Source to indicate the dataset that contains the records that will be added to, subtracted from, or copied to the Destination. If Source is a TQuery component, the query is executed before the move is executed. If a filter is currently in effect on Source, the filter conditions are respected when the batch move executes. The Mode property indicates how the Source records are applied to the Destination:

Mode	Effect on Destination

batAppend	Records are added to the destination table.

batUpdate	Records in the destination table with key fields matching the corresponding fields in the source are changed to match the source records.

batAppendUpdate	Records in the destination table with key fields matching the corresponding fields in the source are changed to match the source. Source records that do not match key fields are added to the destination table.

batDelete	Records in the destination table that match the records in the source are deleted.

batCopy	Destination table is created to match the records in the source.


TBatchMove::Transliterate

TBatchMove	See also

Specifies whether the data in the Source records should be converted form the locale of the Source to the locale of the Destination when the Execute method is called.

__property bool Transliterate = {read=FTransliterate, write=FTransliterate, default=1};

Description

Set Transliterate to true when the Source dataset and the Destination table use different language drivers and the data may contain extended ascii characters. Set Transliterate to false to avoid the overhead of the character set conversion when both the Source and the Destination use the same language driver or the data does not contain extended ascii characters.


TBatchMove methods

TBatchMove	Alphabetically

In TBatchMove

~TBatchMove

Execute

TBatchMove

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBatchMove methods

TBatchMove	By object

~TBatchMove

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TBatchMove


TBatchMove::TBatchMove

TBatchMove	See also

Creates an instance of TBatchMove.

__fastcall virtual TBatchMove(Classes::TComponent* AOwner);

Description

Do not call TBatchMove directly.  Instead, use the new keyword to create a TBatchMove object indirectly. Create instances of TBatchMove for performing batch operations. TBatchMove allocates the memory for the TBatchMove object and

•	Sets AbortOnKeyViol to true.

•	Sets AbortOnProblem to true.

•	Sets Transliterate to true.

•	Creates a TStringList object to hold the Mappings.

The property settings made by TBatchMove are the values used when a TTable object performs batch operations using its BatchMove method.


TBatchMove::~TBatchMove

TBatchMove	See also

Destroys an instance of TBatchMove.

__fastcall virtual ~TBatchMove(void);

Description

Do not call ~TBatchMove directly in an application. Instead, use the delete keyword, which operates on a reference to a TBatchmove object.

Before calling the parent object's destructor, ~TBatchMove frees the TStringList object that implements the Mappings property.


TBatchMove::Execute

TBatchMove	See also 	Example

Peforms the batch operation specified by Mode.

void __fastcall Execute(void);

Description

After setting properties to indicate what batch operation should be performed and how, call Execute to perform the operation. As a minimum, the Mode, Source, and Destination properties must be set.

After calling Execute, the values of the ChangedCount, KeyViolCount, MovedCount, ProblemCount, and RecordCount properties will become available. These properties will give an indication of what happened as a result of the call to Execute. Additional information about the batch operation will be available through the creation of a changed table, a keyviol table, and/or a problems table if it was requested.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent


TBCDField

Hierarchy	Properties	Methods	Events	See also

TBCDField represents a binary-coded decimal (BCD) field in a dataset.

Unit

db

Description

BCD values provide greater precision and accuracy than floating-point numbers. BCD fields are often used for storing and manipulating monetary values. Normally, BCD values are stored and manipulated in decimal (base ten). However, C++Builder does not have a native binary-coded decimal type, so TBCDField uses the System::Currency type to manipulate BCD values. System::Currency uses a binary (base two) format.

Because TBCDField uses the System::Currency type to work with data from BCD fields, TBCDField limits the precision of the BCD values it can support to 4 decimal places and 20 significant digits. The underlying database table may include values that require greater precision. When it encounters such values, TBCDField throws an exception.

As a descendant of TNumericField, TBCDField includes many properties, methods, and events that are useful for managing the value and properties of a numeric field in a database.


TBCDField properties

TBCDField	Alphabetically	Legend

In TBCDField

AsCurrency

AsFloat

AsInteger

AsString

AsVariant

Currency

DataSize

MaxValue

MinValue

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TBCDField properties

TBCDField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ConstraintErrorMessage

Currency

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMaskPtr

EditMask

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Lookup

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TBCDField::AsCurrency

TBCDField	See also

Represents the value of the field as a Currency value.

__property System::Currency AsCurrency = {read=GetAsCurrency, write=SetAsCurrency};

Description

Use AsCurrency to

•	Assign the binary-coded decimal field value to a currency value.

•	Assign a currency value to the binary-coded decimal field.

For example, this code assigns a currency value to a binary-coded decimal field value:

MyBCDField->AsCurrency = CurrencyValue;

To assign a binary-coded decimal field value to a currency value, use code similar to this:

CurrencyVariable = MyBCDField->AsCurrency;

For BCD fields, the AsCurrency property is equivalent to the Value property. Use AsCurrency when you do not know whether or not the field component is a BCD field.

If a value assigned to the field is not within the range established by the MinValue and the MaxValue properties, an EDatabaseError exception is thrown.

Note:	Don’t confuse the AsCurrency property, which converts the type of the data, with the Currency property, which indicates how the data should be formatted.


TBCDField::AsFloat

TBCDField	See also

Represents the value of the field as a floating-point value.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

Use AsFloat to

•	Assign the binary-coded decimal field value to a floating-point value.

•	Assign a floating-point value to the binary-coded decimal field.

For example, this code assigns a floating-point value to a binary-coded decimal field value:

MyBCDField->AsFloat = FloatVariable;

To assign a binary-coded decimal field value to a floating-point value, use code similar to this:

FloatVariable = MyBCDField->AsFloat;

If a value assigned to the field is not within the range established by the MinValue and the MaxValue properties, an EDatabaseError exception is thrown.


TBCDField::AsInteger

TBCDField	See also 	Example

Represents the value of the field as an integer.

__property int AsInteger = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

Use AsInteger to

•	Assign the binary-coded decimal field value to an integer variable.

•	Assign an integer value to the binary-coded decimal field.

For example, this code assigns integer value to a binary-coded decimal field value:

MyBCDField->AsInteger = IntegerVariable;

To assign a binary-coded decimal field value to an integer value, use code similar to this:

IntegerVariable = MyBCDField->AsInteger;

If a value assigned to the field is not within the range established by the MinValue and the MaxValue properties, an EDatabaseError exception is thrown.


TBCDField::AsString

TBCDField	See also

Represents the value of the field as an AnsiString.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to

•	Assign the binary-coded decimal field value to string variable.

•	Assign a string value to the binary-coded decimal field.

For example, this code assigns a string value to a binary-coded decimal field value:

MyBCDField->AsString = "12.32";

To assign a binary-coded decimal field value to a string value, use code similar to this:

NewString = MyBCDField->AsString;

If the string assigned to the field does not represent a valid currency value within the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TBCDField::AsVariant

TBCDField	See also

Represents the value of a binary-coded decimal field as a Variant.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the binary-coded decimal field value to variant value.

•	Assign a variant value to the binary-coded decimal field.

For example, this code assigns a Variant value to a binary-coded decimal field value:

MyBCDField->AsVariant = VariantVariable;

To assign a binary-coded decimal field value to a variant value, use code similar to this:

VariantVariable = MyBCDField->AsVariant;

Using variants is useful when both the actual field type and the type of the data are unknown.

If a value assigned to the field is not within the range established by the MinValue and the MaxValue properties, an EDatabaseError exception is thrown.


TBCDField::currency

TBCDField	See also

Determines whether the value in the field should be formatted as a currency value.

__property bool currency = {read=FCurrency, write=SetCurrency, default=0};

Description

Use the Currency property to influence how the value in the field should be formatted for viewing and editing in a data-aware control.

For display purposes, the field is formatted using the DisplayFormat property if it is assigned. If DisplayFormat is not assigned, currency determines how the field is formatted for display. If currency is true, the value is formatted for display using the FloatToText function with the ffCurrency formatting code. If currency is false, the value is formatted with the ffGeneral format.

For editing purposes, the field is formatted using the EditFormat (or DisplayFormat) property if it is assigned. If neither EditFormat nor DisplayFormat is assigned, currency determines how to format the field for editing. If currency is true, the value is formatted for editing using the FloatToText function with the ffFixed formatting code. If currency is false, the value is formatted with the ffGeneral format.


TBCDField::DataSize

TBCDField	See also 	Example

Indicates the amount of memory needed to store the value of a BCD field in its native binary-coded decimal format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a BCD field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods. GetData and SetData work with the field’s value in native database format rather than the Currency type used by the BCD field object.

For BCD fields, DataSize is always 34. BCD fields are a native type to Paradox tables that take up 34 bytes in a database record.


TBCDField::MaxValue

TBCDField	See also

Limits the maximum value in the binary-coded decimal field.

__property System::Currency MaxValue = {read=FMaxValue, write=SetMaxValue};

Description

Use MaxValue to get or set the maximum value that can be entered into the field. If a value greater than MaxValue is entered, an EDatabaseError exception is thrown.

Newly created BCD fields set MaxValue to the maximum value that can be expressed by the Currency data type.


TBCDField::MinValue

TBCDField	See also

Limits the minimum value in the binary-coded decimal field.

__property System::Currency MinValue = {read=FMinValue, write=SetMinValue};

Description

Use MinValue to get or set the minimum value that can be entered into the field. If a value smaller than MinValue is entered, an EDatabaseError exception is thrown.

Newly created integer fields set MinValue to the minimum value that can be expressed by the Currency data type.


TBCDField::Value

TBCDField	See also

Represents the value of the BCD field as a Currency value.

__property System::Currency Value = {read=GetAsCurrency, write=SetAsCurrency};

Description

Unlike other field types, the Value of a BCD field does not correspond to the physical format of the data that is stored in the underlying database table. C++Builder does not have a native type for binary-coded decimal. Therefore, TBCDField converts the data from a binary-coded decimal value to a Currency value when it fetches the data from the database table, and converts it from a Currency value to a binary-coded decimal value when it posts the data to the database. For BCD fields, Value is the same as the AsCurrency property.

Note:	Because TBCDField works with its data as a Currency value, simply getting the value of the field and posting that value back to the database table can alter the contents of the field. Thus the line

MyBCDField->Value = MyBCDField->Value;

can alter the contents of the field in the database table.


TBCDField events

TBCDField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TBCDField events

TBCDField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TBCDField methods

TBCDField	Alphabetically

In TBCDField

~TBCDField

TBCDField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBCDField methods

TBCDField	By object

~TBCDField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TBCDField

Validate


TBCDField::TBCDField

TBCDField	See also

Creates an instance of TBCDField.

__fastcall virtual TBCDField(Classes::TComponent* AOwner);

Do not call TBCDField directly. Instead, use the new keyword to create a reference to a BCD field at runtime. It is seldom necessary to explicitly create BCD fields because a BCD field component is instantiated automatically for all BCD fields in a dataset.

After calling the parent object's constructor, TBCDField sets the DataType to ftBCD, and initializes the Size to 4.


TBCDField::~TBCDField

TBCDField

Frees the memory associated with the TBCDField object.

__fastcall virtual ~TBCDField(void) { }

Description

Do not call ~TBCDField directly. Instead, use the delete keyword on the object, which causes ~TBCDField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField


TBDECallback

Hierarchy	Methods	See also

TBDECallback is a wrapper for a Borland Database Engine (BDE) callback function.

Unit

dbtables

Description

Use a TBDECallback object to register a callback function with the BDE. Callbacks allow an application to instruct the BDE to take specific actions in response to events that occur during a BDE function call.

For example, the TBatchMove object may encounter problems when executing the corresponding BDE batch operation. A callback function can respond to those problems by instructing the BDE to generate a problems table or to trim the data so that the operation succeeds.

To use a TBDECallback object, take the following steps:

1	Create an instance of TBDECallback to register the callback with the BDE.

2	Call the BDE function in which the pertinent events take place. For example, create an instance of TBatchMove, and call its Execute method.

3	When the BDE function returns, destroy the TBDECallback object to unregister the callback function.


TBDECallback methods

TBDECallback	Alphabetically

In TBDECallback

~TBDECallback

TBDECallback

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBDECallback methods

TBDECallback	By object

~TBDECallback

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TBDECallback


TBDECallback::TBDECallback

TBDECallback	See also

Creates an instance of TBDECallback and registers the specified callback with the Borland Database Engine (BDE).

typedef Bde::CBRType __fastcall (__closure *TBDECallbackEvent)(void * CBInfo);

__fastcall TBDECallback(System::TObject* AOwner, Bde::hDBICur Handle, Bde::CBType CBType, void * CBBuf, int CBBufSize, TBDECallbackEvent &CallbackEvent, bool Chain);

Description

Use TBDECallback to register a callback with the BDE. Do not call the constructor directly. Instead, use the new keyword to create a reference to a new TBDECallback object.

Create a TBDECallback object before calling any BDE function that should use the callback to respond to events. When the BDE encounters the type of event indicated by the CBType parameter, the function specified by the CallbackEvent parameter is called. The CallbackEvent function receives a pointer to a callback descriptor. The type of the callback descriptor varies depending on the CBType. The C++Builder application must allocate the memory for the callback descriptor. A pointer to this memory is passed in as the CBBuf parameter, and its size is given by the CBBufSize parameter.

The Chain parameter indicates whether this callback function should replace any other callbacks of this CBType. When Chain is false, the CallbackEvent function replaces any callbacks registered for the CBType. When Chain is true, the CallbackEvent function is called in addition to other registered callbacks.

The Handle parameter is an optional parameter indicating the database cursor associated with the BDE function that may generate the callback. Provide a Handle to make the callback specific to function calls for that cursor.

The types of callback descriptors associated with each CBType are given in the following table. For more information, see the BDE documentation:::

CBType	Usage	callback descriptor
cbGENPROGRESS	Respond to information about progress during large batch operations. For example, implement a progress bar or cancel button.  Return cbrABORT to cancel, cbrCONTINUE to continue.	CBPROGRESSDesc
cbRESTRUCTURE	Instruct BDE on how to proceed with situations encountered during a table restructure.  Return cbrYES, to proceed with the default handling, cbrNO to proceed without the default behavior, cbrABORT to cancel the restructure.	CBRESTCbDesc
cbBATCHRESULT	Instruct BDE on how to proceed with situations encountered during a batch operation.  Return cbrYES, to proceed with the default handling, cbrNO to proceed without the default behavior, cbrABORT to cancel the batch operation.	CBRESTDbDesc
cbTABLECHANGED	Respond to notifications that a table has changed. The return value is ignored.	not used
cbCANCELQRY	Return cbrABORT to cancel a long running query, or cbrCONTINUE to keep going. The callback is called periodically during the execution of the query.	not used
cbINPUTREQ	Instruct BDE on how to respond when a file (such as a lookup table) is missing.  Indicate the chosen behavior in the CBInputDesc and return cbrCONTINUE.	CBInputDesc
cbDBASELOGIN	Enter a password for an encrypted dBASE table and return cbrCONTINUE.	CBLoginDesc
cbFIELDRECALC	Respond to notifications that fields need to be recalculated. The return value is ignored.	not used
cbTRACE	Respond to trace information about the actions taken by the BDE. The return value is ignored.	TRACEDesc
cbDBLOGIN	Log in to a database server. Return cbrCONTINUE.	not used.
cbDELAYEDUPD	Respond to the notification when cached updates fail to write a modified record to the database.  Return cbrABORT to cancel all cached updates, cbrSKIP or cbrCONTINUE to discard the failed update and continue posting records, cbrRETRY to try the failed commit again.	DELAYUPDCbDesc
Note:	C++Builder uses many BDE callback functions. Calling TBDECallback with Chain set to false may disable the expected behavior of some objects.


TBDECallback::~TBDECallback

TBDECallback	See also

~TBDECallback unregisters the callback and destroys an instance of TBDECallback.

__fastcall virtual ~TBDECallback(void);

Description

Do not call ~TBDECallback directly in an application. Instead, use the delete keyword, which calls ~TBDECallback automatically for a TBDECallback object referenced by a pointer.

~TBDECallback unregisters the callback before freeing the memory associated with the TBDECallback object. After unregistering the callback, any previous callback of the same type will be reinstated.


Hierarchy

TObject


TBDEDataSet

Hierarchy	Properties	Methods	Events	See also

Encapsulates Borland Database Engine (BDE) functionality for descendent dataset objects.

Unit

dbtables

Description

TBDEDataSet is a dataset object that defines BDE functionality for a dataset. Applications never use TBDEDataSet objects directly. Instead they use the descendants of TBDEDataSet and TDBDataSet, such as TQuery, TStoredProc, and TTable, which inherit its database-related properties and methods.

Developers who create custom dataset components that work through the BDE may want to derive them directly from TBDEDataSet to inherit all the functionality of TDataSet and the BDE-related properties and methods of TBDEDataSet. To inherit control over C++Builder database objects, however, most developers should derive custom dataset components that use the BDE from the immediate descendant of TBDEDataSet, TDBDataSet.


TBDEDataSet properties

TBDEDataSet	Alphabetically	Legend

In TBDEDataSet

CacheBlobs

CachedUpdates

CanModify

ExpIndex

Filter

Filtered

FilterOptions

Handle

KeySize

Locale

RecNo

RecordCount

RecordSize

UpdateObject

UpdateRecordTypes

UpdatesPending

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

DataSource

DefaultFields

Designer

EOF

FieldCount

FieldDefs

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TBDEDataSet properties

TBDEDataSet	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CacheBlobs

CachedUpdates

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataSource

DefaultFields

Designer

DesignInfo

EOF

ExpIndex

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Handle

KeySize

Locale

Modified

Name

Owner

RecNo

RecordCount

RecordSize

State

Tag

UpdateObject

UpdateRecordTypes

UpdatesPending

VCLComObject


TBDEDataSet::CacheBlobs

TBDEDataSet

Determines whether BLOBs are cached in memory.

__property bool CacheBlobs = {read=FCacheBlobs, write=FCacheBlobs, default=1};

Description

Use CacheBlobs to specify whether or not to store BLOB images in memory to improve performance when scrolling through records that display BLOB images. CacheBlobs is true by default, meaning that BLOBs are cached in memory. If an application does not need to display the BLOBs associated with records, then set CacheBlobs to false to conserve system resources.


TBDEDataSet::CachedUpdates

TBDEDataSet	See also

Specifies whether cached updates are enabled for a dataset.

__property bool CachedUpdates = {read=FCachedUpdates, write=SetCachedUpdates, default=0};

Description

CachedUpdates enables or disables the use of cached updates for a dataset. If CachedUpdates is true, cached updates are enabled. If CachedUpdates is false, cached updates are disabled.

When cached updates are enabled, updates to a dataset (such as posting changes, inserting new records, or deleting records), are stored in an internal cache on the client machine instead of being written directly to the dataset’s underlying database tables. When changes are complete, an application writes all cached changes to the database in the context of a single transaction.

Cached updates are most useful to client applications working with remote database servers. The main benefits of enabling cached updates are:

•	Fewer transactions and shorter transaction times.

•	Minimization of network traffic.

The potential drawbacks of enabling cached updates are:

•	Other applications can access and change the actual data on the server while users are editing local copies of the data, resulting in an update conflict when cached updates are applied to the database.

•	Other applications cannot access data changes made by an application until its cached updates are applied to the database.


TBDEDataSet::CanModify

TBDEDataSet	See also

Indicates whether the database underlying a dataset permits write access to data.

__property bool CanModify = {read=GetCanModify, nodefault};

Description

Examine CanModify to determine if the database underlying a dataset permits write access to data. When a database connection is established, a dataset typically requests write access. CanModify indicates whether or not write access is granted. If CanModiy is true, data can be modified and written to the database server. If CanModify is false, data can be viewed, but not modified.

Note:	Restrictions on write access for a given user may still prevent writing to an SQL database server even if CanModify is true.


TBDEDataSet::ExpIndex

TBDEDataSet

Indicates whether a dataset is using a dBASE expression index.

__property bool ExpIndex = {read=FExpIndex, nodefault};

Description

Read ExpIndex to determine if a dataset is using a dBASE expression index. If ExpIndex is true, an expression index is in use; otherwise ExpIndex is false.


TBDEDataSet::Filter

TBDEDataSet	See also

Specifies the text of the current filter for a dataset.

__property System::AnsiString Filter = {read=FFilterText, write=SetFilterText};

Description

Use Filter to specify a dataset filter. When filtering is applied to a dataset, only those records that meet a filter’s conditions are available to an application. Filter contains the string that describes the filter condition. For example, the following filter condition displays only those records where the State field is 'CA' or 'MA':

State = 'CA' or State = 'MA'

Note the use of single quotes in the filter expression, rather than the double quotes normally used for strings.

To filter strings bases on partial comparisons, use an asterisk as a wildcard. For example:

State = 'M*'

Note:	Applications can set Filter at runtime to change the filtering condition for a dataset at (for example, in response to user input).


TBDEDataSet::Filtered

TBDEDataSet	See also

Specifies whether filtering is active for a dataset.

__property bool Filtered = {read=FFiltered, write=SetFiltered, default=0};

Description

Check Filtered to determine whether or not dataset filtering is in effect. If Filtered is true, then filtering is active. Otherwise Filtered is false. To apply filter conditions specified in the Filter property or the OnFilterRecord event handler, set Filtered to true.

Note:	When filtering is enabled, user edits to a record may mean that the record no longer meets a filter’s test condition. The next time the record is retrieved from the dataset while the filter is in effect, the record may seem to disappear. If that happens, the next record that passes the filter condition becomes the current record.


TBDEDataSet::FilterOptions

TBDEDataSet	See also

Specifies whether filtering is case insensitive, and whether or not partial comparisons are permitted when filtering records.

enum TFilterOption { foCaseInsensitive, foNoPartialCompare };

typedef Set<TFilterOption, foCaseInsensitive, foNoPartialCompare> TFilterOptions;

__property TFilterOptions FilterOptions = {read=FFilterOptions, write=SetFilterOptions, default=0};

Description

Set FilterOptions to specify whether or not filtering is case insensitive when filtering on string or character fields, and whether or not partial comparisons for matching filter conditions is allowed.

By default, FilterOptions is set to an empty set. For filters based on string fields, include foCaseInsensitive in FilterOptions to catch all variations on a string regardless of capitalization.

To prevent partial string comparisons, include foNoPartialCompare in FilterOptions.

Note:	To filter strings bases on partial comparisons, exclude foNoPartialCompare from FilterOptions and use an asterisk as a wildcard. For example:

State = 'M*'


TBDEDataSet::Handle

TBDEDataSet	See also

Specifies the Borland Database Engine (BDE) cursor handle for the dataset.

__property Bde::hDBICur Handle = {read=FHandle};

Description

Use Handle only to bypass TDataSet methods and call directly into the BDE. Many BDE function calls require a cursor handle parameter. Handle is assigned an initial value when a dataset is opened. If used with a BDE call that changes the current record position, call Resync immediately after returning from the BDE call.

Note:	Do not use this property unless an application requires BDE functionality not available through built-in components.


TBDEDataSet::KeySize

TBDEDataSet

Specifies the size of the key for the current index of the dataset.

__property Word KeySize = {read=FKeySize, nodefault};

Description

Check KeySize to determine the size, in bytes, of the key for the current index. KeySize varies depending on the number and type of fields that make up the current index.


TBDEDataSet::Locale

TBDEDataSet	See also

Identifies the Borland Database Engine (BDE) language driver for the dataset.

__property void * Locale = {read=FLocale};

Description

Examine Locale to determine the BDE language driver for the dataset. Applications that make direct calls to the BDE API may need to pass Locale information as a function parameter.

Language driver information may also be available as one of the values in the Params property of the database component that owns the dataset.

Note:	Do not use this property unless an application requires BDE functionality not available through built-in components.


TBDEDataSet::RecNo

TBDEDataSet	See also

Indicates the current record in the dataset.

__property int RecNo = {read=GetRecNo, write=SetRecNo, nodefault};

Description

Examine RecNo to determine the record number of the current record in the dataset. Applications might use this property with RecordCount to iterate through all the records in a dataset, though typically record iteration is handled with calls to First, Last, MoveBy, Next, and Prior.

Note:	If accessing Paradox tables, RecNo can be set to a specific record number to position the cursor on that record.


TBDEDataSet::RecordCount

TBDEDataSet	See also 	Example

Indicates the total number of records associated with the dataset.

__property int RecordCount = {read=FRecordCount, write=FRecordCount, default=0};

Description

Examine RecordCount to determine the total number of records in the dataset. Applications might use this property with RecNo to iterate through all the records in a dataset, though typically record iteration is handled with calls to First, Last, MoveBy, and Prior.

Note:	Use RecordCount with care, because record counting can be a costly operation, especially for SQL queries that return large result sets. Generally, an application should only use RecordCount with Paradox and dBASE tables.


TBDEDataSet::RecordSize

TBDEDataSet	See also

Indicates the size of a record in the dataset.

__property Word RecordSize = {read=GetRecordSize, nodefault};

Description

Examine RecordSize to determine the physical size, in bytes, of the buffer C++Builder allocates to hold a record in the dataset. When a dataset is opened, the Open procedure requests record-buffer size information from the Borland Database Engine (BDE) and stores the returned information in RecordSize. C++Builder uses this information internally. Applications seldom, if ever, require this information.


TBDEDataSet::UpdateObject

TBDEDataSet	See also

Specifies the update object component used to update a read-only result set when cached updates are enabled.

__property TDataSetUpdateObject* UpdateObject = {read=FUpdateObject, write=SetUpdateObject};

Description

Use UpdateObject to specify the TUpdateObject component to use in an application that must be able to update a read-only result set returned by the Borland Database Engine (BDE).

The BDE always attempts to provide an updateable, or “live” query result unless an application specifically requests a read-only view of data. In some cases, such as a query made against multiple tables, a live result set cannot be returned. In these cases, UpdateObject can be used to specify a TUpdateSQL component that performs updates as a separate transaction that is transparent to the application.


TBDEDataSet::UpdateRecordTypes

TBDEDataSet	See also 	Example

Specifies the type of records visible in a dataset when cached updates are enabled.

enum DBTables__9 { rtModified, rtInserted, rtDeleted, rtUnmodified };

typedef Set<DBTables__9, rtModified, rtUnmodified>  TUpdateRecordTypes;

__property TUpdateRecordTypes UpdateRecordTypes = {read=GetUpdateRecordSet, write=SetUpdateRecordSet, nodefault};

Description

Use UpdateRecordTypes to specify the records that are visible in a dataset when cached updates are enabled. UpdateRecordTypes is a set that can have the following values:

Value	Meaning

rtModified	Modified records are visible.

rtInserted	Inserted records are visible.

rtDeleted	Deleted records are visible.

rtUnmodified	Unmodified records are visible.

By default, a dataset is created with an UpdateRecordTypes set of [rtModified, rtInserted, rtUnmodified], meaning that all existing, edited, or inserted records are visible to the user.

An application that must cycle through a dataset to undelete records may change UpdateRecordTypes as part of an undelete method, so that deleted records are “visible” long enough to restore them to their previously undeleted conditions.

An application might also use UpdateRecordTypes like a filter to temporarily limit visible records to those added or inserted by the user during the current session.


TBDEDataSet::UpdatesPending

TBDEDataSet	See also	Example

Indicates whether the cached updates buffer contains records that are not yet applied.

__property bool UpdatesPending = {read=GetUpdatesPending, nodefault};

Description

Examine UpdatesPending to check the status of the cached updates buffer. If UpdatesPending is true, then there are edited, deleted, or inserted records to apply to the database. If UpdatesPending is false, there are no records in the cache.


TBDEDataSet events

TBDEDataSet	Alphabetically	Legend

In TBDEDataSet

OnServerYield

OnUpdateError

OnUpdateRecord

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TBDEDataSet events

TBDEDataSet	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnServerYield

OnUpdateError

OnUpdateRecord


TBDEDataSet::OnServerYield

TBDEDataSet	See also

Occurs during processing of a query on a remote database server when the server sends a yield call back to the Borland Database Engine (BDE).

typedef void __fastcall (__closure *TOnServerYieldEvent)(Db::TDataSet* DataSet, bool &AbortQuery);

__property TOnServerYieldEvent OnServerYield = {read=FOnServerYield, write=FOnServerYield};

Description

Write an OnServerYield event handler to respond to a BDE callback generated when a database server yields temporary control to the BDE during a query operation. When it receives such control, it calls OnServerYield if the handler exists.

To continue processing the query, OnServerYield should set the AbortQuery parameter to false. To end query processing set AbortQuery to true.

Note:	Currently, only Sybase yields control during query processing.


TBDEDataSet::OnUpdateError

TBDEDataSet	See also

Occurs if an exception is generated when cached updates are applied to a database.

enum TUpdateKind { ukModify, ukInsert, ukDelete };

enum TUpdateAction { uaFail, uaAbort, uaSkip, uaRetry, uaApplied };

typedef void __fastcall (__closure *TUpdateErrorEvent)(Db::TDataSet* DataSet, Db::EDatabaseError* E, Db::TUpdateKind UpdateKind, TUpdateAction &UpdateAction);

__property TUpdateErrorEvent OnUpdateError = {read=FOnUpdateError, write=SetOnUpdateError};

Description

Write an OnUpdateError event handler to respond to exceptions generated when cached updates are applied to a database.

Because there is a delay between the time a record is first cached and the time cached updates are applied, there is a possibility that another application may change one or more of the same records in the database before the cached changes can be applied. The Borland Database Engine (BDE) checks for this condition and throws an exception. C++Builder responds by calling the OnUpdateError event handler if it exists.

DataSet is the name of the dataset to which updates are applied.

E is a pointer to a EDBEngineError object from which an application can extract an error message and the actual cause of the error condition. An OnUpdateError handler can use this information to determine how to respond to the error condition.

UpdateKind describes the type of update that generated the error. The following table lists the possible values for UpdateKind and what they indicate:

Value	Meaning

ukModify	Editing an existing record caused an error.

ukInsert	Inserting or appending a new record caused an error.

ukDelete	Deleting an existing record raised an error.

UpdateAction indicates the action to take when the OnUpdateError handler exits. On entry into the handler, UpdateAction is always set to uaFail. If OnUpdateError can handle or correct the error, set UpdateAction to uaRetry before exiting the error handler. The following table lists the possible values for UpdateAction and what they indicate:

Value	Meaning

uaAbort	Aborts the update operation without displaying an error message.

uaApplied	Not used in error handling routines.

uaFail	Aborts the update operation and displays an error message.

uaRetry	Repeats the update operation that originally raised the error condition.

uaSkip	Skips updating the record that raised the error condition, and leaves the unapplied changes in the cache.

The error handler can use the TField::OldValue and TField::NewValue properties to evaluate error conditions and set TField::NewValue to a new value to reapply. In this case, set UpdateAction to uaRetry before exiting.

Note:	If a call to ApplyUpdates throws an exception and ApplyUpdates is not called within the context of a try...catch block, an error message is displayed. If an OnUpdateError handler cannot correct the error condition and leaves UpdateAction set to uaFail, the error message is displayed twice. To prevent redisplay, set UpdateAction to uaAbort in the error handler.

Important:	The code in an OnUpdateError handler must not call any methods that make a different record the current one.


TBDEDataSet::OnUpdateRecord

TBDEDataSet	See also

Occurs when cached updates are applied to a record.

enum TUpdateKind { ukModify, ukInsert, ukDelete };

enum TUpdateAction { uaFail, uaAbort, uaSkip, uaRetry, uaApplied };

typedef void __fastcall (__closure *TUpdateRecordEvent)(Db::TDataSet* DataSet, Db::TUpdateKind UpdateKind, TUpdateAction &UpdateAction);

__property TUpdateRecordEvent OnUpdateRecord = {read=FOnUpdateRecord, write=FOnUpdateRecord};

Description

Write an OnUpdateRecord event handler to process updates that cannot be handled by a single update component, such as implementation of cascading updates, insertions, or deletions. This handler is also useful for applications that require additional control over parameter substitution in update components.

DataSet is the name of the dataset to which updates are applied.

UpdateKind describes the type of update to perform. The following table lists the possible values for UpdateKind and what they indicate:

Value	Meaning

ukModify	Edit an existing record.

ukInsert	Insert or append a new record.

ukDelete	Delete an existing record.

UpdateAction indicates the action taken by the OnUpdateRecord handler before it exits. On entry into the handler, UpdateAction is always set to uaFail. If OnUpdateRecord is successful, it should set UpdateAction to uaApplied before exiting. The following table lists the possible values for UpdateAction and what they indicate:

Value	Meaning

uaAbort	Abort the update operation without displaying an error message.

uaApplied	Update is applied. Free update record from cache.

uaFail	Aborts the update operation and displays an error message.

uaRetry	Not used for record updates.

uaSkip	Update is skipped. Leave update record in the cache.

Note:	The code in an OnUpdateRecord handler must not call any methods that make a different record the current one.


TBDEDataSet methods

TBDEDataSet	Alphabetically

In TBDEDataSet

~TBDEDataSet

ApplyUpdates

BookmarkValid

Cancel

CancelUpdates

CommitUpdates

CompareBookmarks

ConstraintCallBack

ConstraintsDisabled

CreateBlobStream

DisableConstraints

EnableConstraints

FetchAll

FlushBuffers

GetCurrentRecord

GetIndexInfo

IsSequenced

Locate

Lookup

Post

RevertRecord

TBDEDataSet

Translate

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Prior

Refresh

Resync

SetFields

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBDEDataSet methods

TBDEDataSet	By object

~TBDEDataSet

ActiveBuffer

Append

AppendRecord

ApplyUpdates

Assign

BookmarkValid

Cancel

CancelUpdates

CheckBrowseMode

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CommitUpdates

CompareBookmarks

ConstraintCallBack

ConstraintsDisabled

ControlsDisabled

CreateBlobStream

CursorPosChanged

DefaultHandler

Delete

DestroyComponents

Destroying

DisableConstraints

DisableControls

Dispatch

Edit

EnableConstraints

EnableControls

FetchAll

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FlushBuffers

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GotoBookmark

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

IsSequenced

Last

Locate

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

Post

Prior

Refresh

RemoveComponent

Resync

RevertRecord

SafeCallException

SetFields

TBDEDataSet

Translate

UpdateCursorPos

UpdateRecord

UpdateStatus


TBDEDataSet::ApplyUpdates

TBDEDataSet	See also 	Example

Writes a dataset’s pending cached updates to the database.

void __fastcall ApplyUpdates(void);

Description

Call ApplyUpdates to write a dataset’s pending cached updates to a database. This method passes cached data to the database for storage, but the changes are not committed to the database. An application must explicitly call the database component’s Commit method to commit the changes to the database if the write is successful, or call the database’s Rollback method to undo the changes if there is an error.

Following a successful write to the database, and following a successful call to the database’s Commit method, an application should call the CommitUpdates method to clear the cached update buffer.

Note:	The preferred method for updating datasets is to call a database component’s ApplyUpdates method rather than to call each individual dataset’s ApplyUpdates method. The database component’s ApplyUpdates method takes care of committing and rolling back transactions and clearing the cache when the operation is successful.


TBDEDataSet::BookmarkValid

TBDEDataSet	See also

Tests the validity of a specified bookmark.

virtual bool __fastcall BookmarkValid(void * Bookmark);

Description

Call BookmarkValid to determine if a specifed bookmark is currently assigned a value. Bookmark specifies the bookmark to test.

BookmarkValid returns true if a bookmark is valid. Otherwise, it returns false.


TBDEDataSet::Cancel

TBDEDataSet	See also 	Example

Cancels modifications to the current record if those changes are not yet posted.

virtual void __fastcall Cancel(void);

Description

Call Cancel to undo modifications made to one or more fields belonging to the current record. As long as those changes are not already posted to the database, Cancel returns the record to its previous state, and sets the dataset state to dsBrowse.

Typically Cancel is used to back out of changes in response to user request, or in field validation routines that back out illegal field values. The TDBNavigator object contains a Cancel button that triggers a call to Cancel.


TBDEDataSet::CancelUpdates

TBDEDataSet	See also

Clears all pending cached updates from the cache and restores the dataset its prior state.

void __fastcall CancelUpdates(void);

Description

Call CancelUpdates to clear all pending cached updates from the cache and restore the dataset to the state it was in when the table was opened, cached updates were last enabled, or updates were last successfully applied to the database.

When a dataset is closed, or the CachedUpdates property is set to false, CancelUpdates is called automatically.

Note:	To undo changes to a single record, call RevertRecord.


TBDEDataSet::CommitUpdates

TBDEDataSet	See also 	Example

Clears the cached updates buffer.

void __fastcall CommitUpdates(void);

Description

Call CommitUpdates to clear the cached updates buffer after both a successful call to ApplyUpdates and a database component’s Commit method. Clearing the cache after applying updates ensures that the cache is empty except for records that could not be processed and were skipped by the OnUpdateRecord or OnUpdateError event handlers. An application can attempt to modify the records still in the cache.

Record modifications made after a call to CommitUpdates repopulate the cached update buffer and require a subsequent call to ApplyUpdates to move them to the database.

Note:	Applications that use a database component’s ApplyUpdates method to apply and commit pending updates for all datasets associated with the database component do not need to call CommitUpdates.


TBDEDataSet::CompareBookmarks

TBDEDataSet	See also

Indicates the relationship between two bookmarks.

virtual int __fastcall CompareBookmarks(void * Bookmark1, void * Bookmark2);

Description

Call CompareBookmarks to determine if two bookmarks are identical or not. Bookmark1 and Bookmark2 are the bookmarks to compare.

If the bookmarks differ, CompareBookmarks returns 1. If the Bookmarks are identical, or both bookmarks are NULL, CompareBookmarks returns 0.


TBDEDataSet::ConstraintCallBack

TBDEDataSet	See also

Specifies the callback function that allows the dataset to communicate with the BDE constraint layer.

Word __stdcall ConstraintCallBack(Bde::DsInfoReq Req, Bde::DataSources &ADataSources);

Description

Use the address of ConstraintCallBack as a parameter when making direct API calls to Borland Database Engine (BDE) functions that require a callback to provide information about the constraints on the dataset or its fields.


TBDEDataSet::ConstraintsDisabled

TBDEDataSet	See also

Indicates whether or not constraints are enabled for a dataset.

bool __fastcall ConstraintsDisabled(void);

Description

Call ConstraintsDisabled to determine if constraints are currently disabled for a dataset. If ConstraintsDisabled returns true, constraints are currently disabled. If false, constraints are currently enabled.


TBDEDataSet::TBDEDataSet

TBDEDataSet	See also

Creates an instance of a TBDEDataSet component.

__fastcall virtual TBDEDataSet(Classes::TComponent* AOwner);

Description

Do not instantiate a TBDEDataSet object at runtime. Instead, instantiate a TBDEDataSet descendant, such as TTable, TQuery, or TStoredProc.

TBDEDataSet:

•	Calls its parent object's constructor method.

•	Set the Locale property of the dataset to the locale of the default session.

•	Sets the CacheBlobs property to true.


TBDEDataSet::TBDEDataSet
TBDEDataSet::CreateBlobStream

TBDEDataSet	See also 	Example

Returns a TBlobStream object for reading or writing the data in a specified blob field.

virtual Classes::TStream* __fastcall CreateBlobStream(Db::TField* Field, Db::TBlobStreamMode Mode);

Description

Call CreateBlobStream to obtain a stream for reading data from or writing data to a binary large object (BLOB) field. The Field parameter must specify a TBlobField component from the Fields property array. The Mode parameter specifies whether the stream will be used for reading, writing, or updating the contents of the field.


TBDEDataSet::~TBDEDataSet

TBDEDataSet	See also

Destroys the instance of a dataset component.

__fastcall virtual ~TBDEDataSet(void);

Description

Do not call ~TBDEDataSet directly in an application. Usually destruction of datasets is handled automatically by C++Builder. If an application creates its own instances of a dataset, however, the application use the delete keyword to destroy the dataset.

~TBDEDataSet calls the parent class's destructor if necessary, frees the resources allocated for the BDE asynchronous callback, and sets the UpdateObject property for the dataset to NULL.


TBDEDataSet::DisableConstraints

TBDEDataSet	See also

Disables application of server constraints on the dataset.

void __fastcall DisableConstraints(void);

Description

Call DisableConstraints to prevent, on a temporary basis, application of server constraints replicated to the dataset. For example, when an application iterates through a dataset, it may improve performance to disable constraints temporarily.

Note:	Calling DisableConstraints increments a reference count. As long as this reference count is greater than zero, constraints are disabled for the dataset. To prevent accidental disabling of constraints, always group a call to DisableConstraints with a call to EnableConstraints.


TBDEDataSet::EnableConstraints

TBDEDataSet	See also

Enables application of server constraints against dataset entries.

void __fastcall EnableConstraints(void);

Description

Call EnableConstraints to turn on application server constraints previously disabled by a call to DisableConstraints.

Note:	Calling EnableConstraints decrements a reference count. When this reference count is zero constraints are enabled for the dataset. To prevent accidental disabling of constraints, always follow a call to DisableConstraints with a matching call to EnableConstraints.


TBDEDataSet::FetchAll

TBDEDataSet	See also

Retrieves all records from the current cursor position to the end of the file and stores them locally.

void __fastcall FetchAll(void);

Description

Call FetchAll to reduce network traffic when using cached updates. FetchAll calls CheckBrowseMode to post any pending changes, and then retrieves all records from the current cursor position to the end of the file, and store them locally.

Ordinarily when cached updates are enabled, a transaction retrieves only as much data as it needs for display purposes. Each new fetch starts a new, read-only transaction. To consolidate transactions and reduce network traffic, an application can call FetchAll to retrieve all data in a single transaction.

Note:	Using FetchAll is not always appropriate. For example, when an application accesses a database used by many simultaneous clients and there is a high degree of contention for updating the same records, fetching all records at once may not be advantageous because some fetched records may be changed by other applications. Always weigh the advantages of reduced network traffic against the need for reduced record contention.


TBDEDataSet::FlushBuffers

TBDEDataSet	See also

Posts all changes that have been written to the record buffer.

void __fastcall FlushBuffers(void);

Description

Call FlushBuffers to cause the dataset to post all pending changes to the database, including any cached updates. Use FlushBuffers instead of CheckBrowseMode if it is important that cached record buffers are posted.


TBDEDataSet::GetCurrentRecord

TBDEDataSet	See also

Retrieves the current record into a buffer.

virtual bool __fastcall GetCurrentRecord(char * Buffer);

Description

Most applications should not need to call GetCurrentRecord. TDataSet automatically allocates a buffer for the active record.

Call GetCurrentRecord to copy the current record into a buffer allocated by the application. Buffer must be at least as big as the record size indicated by the RecordSize property.


TBDEDataSet::GetIndexInfo

TBDEDataSet	See also

Retrieves information about the current index into the index data fields of the dataset.

void __fastcall GetIndexInfo(void);

Description

Call GetIndexInfo to update information about the current index. Ordinarily an application does not need to call GetIndexInfo because this routine is used internally to retrieve index information as needed. Some applications, however, may want to ensure that the index information used by the dataset is up-to-date.

GetIndexInfo queries the BDE for index information, including:

•	Whether or not the current index is a dBASE expression index.

•	Whether or not the index is case insensitive.

•	The number of fields that make up the key for the index.

•	The field map for the index.

•	The size of the index key.

Number of fields and field map are not retrieved if the index is a dBASE expression index.


TBDEDataSet::IsSequenced

TBDEDataSet	See also

Indicates whether sequence numbers are available for database records.

virtual bool __fastcall IsSequenced(void);

Description

Call IsSequenced to determine whether database records can be located by sequence numbers. When IsSequenced is true, the dataset can navigate directly to a specific record by setting the RecNo property. If IsSequenced is false, the only way to navigate to a specific record is to start at the beginning and count records.


TBDEDataSet::Locate

TBDEDataSet	See also

Searches the dataset for a specified record and makes that record the current record.

enum TLocateOption { loCaseInsensitive, loPartialKey };

typedef Set<TLocateOption, loCaseInsensitive, loPartialKey>  TLocateOptions;

virtual bool __fastcall Locate(const System::AnsiString KeyFields, const System::Variant &KeyValues, Db::TLocateOptions Options);

Description

Call Locate to search a dataset for a specific record and position the cursor on it. KeyFields is a string containing a semicolon-delimited list of field names on which to search.

KeyValues is a variant array containing the values to match in the key fields. To specify multiple search values, pass KeyValues as a variant array as an argument. For example:

TLocateOptions Opts;

Opts.Clear();

Opts << loPartialKey;

Variant locvalues[2];

locvalues[0] = Variant("Sight Diver");

locvalues[1] = Variant("P");

CustTable->Locate("Company;Contact", VarArrayOf(locvalues, 1), Opts);

Options is a set that optionally specifies additional search latitude when searching on string fields. If Options contains the loCaseInsensitive setting, then Locate ignores case when matching fields. If Options contains the loPartialKey setting, then Locate finds the first record that fulfills at least some initial part of the KeyValues criteria for record matching. If Options is an empty set, or if the KeyFields are not string fields, Options is ignored.

Locate returns true if it finds a matching record, and makes that record the current one. Otherwise Locate returns false.

Locate uses the fastest possible method to locate matching records. If the search fields in KeyFields are indexed and the index is compatible with the specified search options, Locate uses the index. Otherwise Locate creates a filter for the search.


TBDEDataSet::Lookup

TBDEDataSet	See also

Retrieves field values from a record that matches specified search values.

virtual System::Variant __fastcall Lookup(const System::AnsiString KeyFields, const System::Variant &KeyValues, const System::AnsiString ResultFields);

Description

Call Lookup to retrieve values for specified fields from a record that matches search criteria. KeyFields is a string containing a semicolon-delimited list of field names on which to search.

KeyValues is a variant array containing the values to match in the key fields. To specify multiple search values, pass KeyValues as a variant array as an argument, or construct a variant array on the fly using the VarArrayOf routine.

ResultFields is a string containing a semicolon-delimited list of field names whose values should be returned from the matching record.

Lookup returns a variant array containing the values from the fields specified in ResultFields.

Lookup uses the fastest possible method to locate matching records. If the search fields in KeyFields are indexed, Lookup uses the index. Otherwise Lookup creates a filter for the search.


TBDEDataSet::Post

TBDEDataSet	See also 	Example

Writes a modified record to the database.

virtual void __fastcall Post(void);

Description

Call Post to write a modified record to the database. Dataset methods that change the dataset state, such as Edit, Insert, or Append, or that move from one record to another, such as First, Last, Next, and Prior automatically call Post.


TBDEDataSet::RevertRecord

TBDEDataSet	See also 	Example

Restores the current record in the dataset to an unmodified state when cached updates are enabled.

void __fastcall RevertRecord(void);

Description

Call RevertRecord to undo changes made to the current record when cached updates are enabled.

Note:	To undo all changes to all pending updates in the cache, call CancelUpdates.


TBDEDataSet::Translate

TBDEDataSet

Converts a data string between the ANSI character set used by C++Builder (and Windows), and the local code page (OEM character set).

virtual void __fastcall Translate(char * Src, char * Dest, bool ToOem);

Description

When the ToOem parameter is true, Translate converts the source string from the ANSI character set to the OEM character set.  If ToOem is false, Translate converts the source string from the OEM character set to the ANSI character set.  By default, BDE datasets work with strings in the OEM character set.  C++Builder uses the ANSI character set (which is used by Windows).  Use the Translate method to convert between these two.


TBDEDataSet::UpdateStatus

TBDEDataSet	See also

Reports the current update status for the dataset.

Db::TUpdateStatus __fastcall UpdateStatus(void);

Description

Call UpdateStatus to determine the current update status for the dataset when cached updates are enabled. Update status can change frequently as records are edited, inserted, or deleted. UpdateStatus offers a convenient method for applications to assess the current status before undertaking or completing operations that depend on the update status of the dataset.

The return value of the UpdateStatus method is one of the following:

Value	Description
usUnmodified	Record contents have not been changed
usModified	Record contents have been changed
usInserted	Record has been inserted
usDeleted	Record has been deleted


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet


 TBevel

Hierarchy	Properties	Methods	See also

TBevel represents a beveled outline.

Unit

extctrls

Description

Use TBevel to create beveled boxes, frames, or lines. The bevel can appear raised or lowered.


TBevel properties

TBevel	Alphabetically	Legend

In TBevel

Shape

Style

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TBevel properties

TBevel	By object	Legend

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Height

Hint

Left

Name

Owner

Parent

ParentShowHint

Shape

ShowHint

Style

Tag

Top

VCLComObject

Visible

Width

WindowProc


TBevel::Shape

TBevel	See also	Example

Determines the shape of the bevel.

__property TBevelShape Shape = {read=FShape, write=SetShape, default=0};

Description

Set Shape to specify whether the bevel appears as a line, a box, or a frame. These are the possible values of Shape:

Value	Meaning

bsBox	The entire client area appears raised or lowered, depending on the value of Style.

bsFrame	The client area is outlined by a raised or lowered frame.

bsTopLine	The bevel displays a line at the top of the client area.

bsBottomLine	The bevel displays a line at the bottom of the client area.

bsLeftLine	The bevel displays a line at the left side of the client area.

bsRightLine	The bevel displays a line at the right side of the client area.


TBevel::Style

TBevel	See also	Example

Determines whether the bevel appears raised or lowered.

__property TBevelStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

Set Style to indicate whether the bevel should create a raised or a lowered effect. When the Shape property is bsBox, the entire client area appears raised or lowered. For all other values of Shape, the bevel displays a raised or lowered line along the edge or edges of the client area. These are the possible values of Style:

Value	Meaning

bsLowered	The bevel is lowered.

bsRaised	The bevel is raised.


TBevel methods

TBevel	Alphabetically

In TBevel

~TBevel

TBevel

Derived from TGraphicControl

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBevel methods

TBevel	By object

~TBevel

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TBevel

Update


TBevel::TBevel

TBevel	See also

Creates and initializes an instance of TBevel.

__fastcall virtual TBevel(Classes::TComponent* AOwner);

Description

Do not call TBevel directly. Instead, use the keyword new, which returns an indirect reference to the new TBevel object.


TBevel::~TBevel

TBevel

~TBevel frees the memory associated with the TBevel object.

__fastcall virtual ~TBevel(void) { }

Description

Do not call ~TBevel directly. Instead, use the delete keyword on the object, which causes ~TBevel to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


TBinaryField

Hierarchy	Properties	Methods	Events	See also

TBinaryField represents an untyped binary field in a dataset.

Unit

db

Description

TBinaryField is an abstract object that encapsulates the fundamental behavior common to untyped binary fields. In addition to the properties, methods, and events common to all fields that are introduced by the TField class, TBinaryField reimplements the properties that are needed to read and write binary data from or to the underlying database table.

Do not create instances of TBinaryField. TBinaryField descendants are created automatically each time a dataset is activated.


TBinaryField properties

TBinaryField	Alphabetically	Legend

In TBinaryField

AsString

AsVariant

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TBinaryField properties

TBinaryField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TBinaryField::AsString

TBinaryField	See also

Represents the value of a binary field as an AnsiString.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to read or write the value of the field as a string. AnsiString values are not limited to text, so the value represented by AsString is the same as the unformatted binary value of the field. When setting the value of AsString, if the assigned value is longer than the DataSize of the field, it will be truncated to include only DataSize bytes.

Note: Reading the Text property of a binary field gives the field name of the field, not the value of AsString.


TBinaryField::AsVariant

TBinaryField	See also

Represents the value of a binary field as a variant array of Byte values.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to read or write the value of the field as a variant array of byte values. For example, this code assigns a variant array of bytes to a binary field value:

Variant V = VarArrayCreate(OPENARRAY(int,(0,BinaryField->DataSize - 1)),varByte);

V[0] = 1;

...

BinaryField->AsVariant = V;

To assign a binary field value to a variant variable, use code similar to this:

Variant V = MyBinaryField->AsVariant;

Because binary fields are stored in their database tables as unformatted arrays of bytes, the AsVariant property for a binary field is the same as the Value property.


TBinaryField::Value

TBinaryField	See also

Represents the data in the binary field.

Description

__property System::Currency Value = {read=GetAsCurrency, write=SetAsCurrency};

Use Value to read data from and write data to a binary field component at runtime. For binary fields, the Value property is equivalent to the AsVariant property.


TBinaryField events

TBinaryField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TBinaryField events

TBinaryField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TBinaryField methods

TBinaryField	Alphabetically

In TBinaryField

~TBinaryField

TBinaryField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBinaryField methods

TBinaryField	By object

~TBinaryField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TBinaryField

Validate


TBinaryField::TBinaryField

TBinaryField	See also

Creates an instance of TBinaryField.

__fastcall virtual TBinaryField(Classes::TComponent* AOwner);

Description

Do not call the constructor directly to create a binary field at runtime. Instead, use the new keyword to create a reference to a binary field. Most applications do not need to create binary fields. Binary fields are automatically created by the dataset that contains them.

TBinaryField simply calls the ancestor object's constructor.


TBinaryField::~TBinaryField

TBinaryField

Frees the memory associated with the TBinaryField object.

__fastcall virtual ~TBinaryField(void) { }

Description

Do not call ~TBinaryField directly. Instead, use the delete keyword on the object, which causes ~TBinaryField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField


 TBitBtn

Hierarchy	Properties	Methods	Events	See also

TBitBtn is a push button control that can include a bitmap on its button face.

Unit

buttons

Description

Bitmap buttons have the general behavior of button controls. Use them to initiate actions from forms and dialog boxes.

Bitmap buttons have additional properties used to specify the bitmap images, their appearance and placement on the button. You can choose from predefined bitmap buttons styles or use your own, customized bitmap for the button. Although the button can be associated with only a single bitmap, the bitmap (glyph property) can be subdivided into four equally sized portions which display based on the state of the button: up, down, and disabled (note that speed buttons can make use of the fourth part of the glyph with their fourth state called “stay down”).

The Kind property of TBitBtn lets you easily create buttons that have common behaviors, such as Ok, Cancel, Help, and so on. These predefined button types have appropriate graphical images and default behaviors, so you can easily add common button types to your application without being distracted with the coding overhead.


TBitBtn properties

TBitBtn	Alphabetically	Legend

In TBitBtn

Glyph

Kind

Layout

Margin

NumGlyphs

Spacing

Style

Derived from TButton

Cancel

Default

ModalResult

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TBitBtn properties

TBitBtn	By object	Legend

Align

BoundsRect

Brush

Cancel

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

Default

DesignInfo

DragCursor

DragMode

Enabled

Font

Glyph

Handle

Height

HelpContext

Hint

Kind

Layout

Left

Margin

ModalResult

Name

NumGlyphs

Owner

Parent

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

Spacing

Style

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TBitBtn::Glyph

TBitBtn	See also	Example

Specifies the bitmap that appears on the selected bitmap button.

__property Graphics::TBitmap* Glyph = {read=GetGlyph, write=SetGlyph, stored=IsCustom};

Description

Use the Open dialog box that appears as an editor in the Object Inspector to choose a bitmap file (with a .BMP extension) to use on the button, or specify a bitmap file at runtime.

You can provide up to four images within a single bitmap. All images must be the same size and next to each other in a row. Bit buttons display one of these images depending on their state.

Image position	Button state	Description
First	Up	This image appears when the button is up (unselected). This image is also used when the button has focus (for example, if the user tabs to it); in this case, a focus rectangle is drawn around the button. If no other images exist in the bitmap, bit buttons use this image for all other states.
Second	Disabled	This image usually appears dimmed to indicate that the button can't be selected.
Third	Clicked	This image appears when the button is clicked. The Up image reappears when the user releases the mouse button.
Fourth	Down	This image appears when the button stays down (indicating that it remains selected).
If only one image is present, bit buttons attempt to represent the other states by altering the image slightly for the different states, although the Down state is always the same as the Up state. If you aren't satisfied with the results, you can provide additional images in the bitmap.

If you have multiple images in a bitmap, you must specify the number of images that are in the bitmap with the NumGlyphs property.

Note:	The lower left hand pixel of the bitmap is reserved for the “transparent” color. Any pixel in the bitmap which matches that lower left hand pixel will be transparent.


TBitBtn::Kind

TBitBtn	See also 	Example

Determines the kind of bitmap button.

enum TBitBtnKind { bkCustom, bkOK, bkCancel, bkHelp, bkYes, bkNo, bkClose, bkAbort, bkRetry, bkIgnore, bkAll };

__property TBitBtnKind Kind = {read=GetKind, write=SetKind, default=0};

Description

The TBitBtnKind type contains the values the Kind property of a TBitBtn bitmap button can assume.

These are the possible values and their meanings:

Value	Meaning

bkCustom	The button uses the Glyph property to determine the image that appears. As with push buttons, select a ModalResult for the button, or supply the code to respond to an OnClick event.

bkOK	A green check mark and the text “OK” appear on the button face. The button becomes the default button (the Default property is automatically set to true). When the user chooses the button, the dialog box closes. The resulting ModalResult value of the bitmap button is mrOK.

bkCancel	A red X and the text “Cancel” appear on the button face. The button becomes the Cancel button (the Cancel property is automatically set to true). When the user chooses the button, the dialog box closes. The resulting ModalResult value of the bitmap button is mrCancel.

bkYes	A green check mark and the text “Yes” appear on the button face. The button becomes the default button (the Default property is automatically set to true). When the user chooses the button, any changes the user made in the dialog box are accepted and the dialog box closes. The resulting ModalResult value of the bitmap button is mrYes.

bkNo	A red no symbol and the text “No” appear on the button face. The button becomes the Cancel button (the Cancel property is automatically set to true). When the user chooses the button, any changes the user made in the dialog box are canceled and the dialog box closes. The resulting ModalResult value of the bitmap button is mrNo.

bkHelp	A cyan question mark and the text “Help” appear on the button face. When the user chooses the button, a Help screen in the application's Help file appears. The Help file that appears is the file specified as the value of the application's HelpFile property. The value of the HelpContext property of the button specifies which Help screen in the Help file appears.

bkClose	A door with a green exit sign over it and the text “Close” appear on the button face. When the user chooses the button, the form closes. The Default property of the button is true.

bkAbort	A red X and the text “Abort” appear on the button face.

bkRetry	A green circular arrow and the text “Retry” appear on the button face.

bkIgnore	A green man walking away and the text “Ignore” appear on the button face. Use it to allow the user to continue after an error has occurred.

bkAll	A double green check mark and the text “Yes to All” appear on the button face.


TBitBtn::Layout

TBitBtn	See also	Example

Determines where the image appears on the bitmap button.

enum TButtonLayout { blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom };

__property TButtonLayout Layout = {read=FLayout, write=SetLayout, default=0};

Description

The TButtonLayout type defines the values the Layout property of a bitmap button (TBitBtn). These are the possible values:

Value	Meaning

blGlyphLeft	The image appears at the left side of the text or caption.

blGlyphRight	The image appears at the right side of the text or caption.

blGlyphTop	The image appears at the top of the text or caption.

blGlyphBottom	The image appears at the bottom of the text or caption.


TBitBtn::Margin

TBitBtn	See also	Example

Determines the number of pixels between the edge of the image (specified in the Glyph property) and the edge of the button.

__property int Margin = {read=FMargin, write=SetMargin, default=-1};

Description

The edges that the margin separates depends on the layout of the image and text (specified in the Layout property). For example, if Layout is blGlyphLeft, the margin appears between the left edge of the image and the left edge of the button. If Margin is 3, three pixels separates the image and the button edges. If Margin is 0, no distance in pixels separates the image and the button edges.

If Margin is -1 (the default value), then the image and text (specified in the Caption property) are centered. The number of pixels between the image and button edge is equal to the number of pixels between the opposite edge of the button and the text.


TBitBtn::NumGlyphs

TBitBtn	See also

Indicates the number of images that are in the graphic specified in the Glyph property for use on a bitmap button or speed button.

typedef Shortint TNumGlyphs;

__property TNumGlyphs NumGlyphs = {read=GetNumGlyphs, write=SetNumGlyphs, stored=IsCustom, default=1};

Description

If you have multiple images in a bitmap, you must specify the number of images that are in the bitmap with the NumGlyphs property. Valid NumGlyphs values are 1 to 4. The default value is 1.


TBitBtn::Spacing

TBitBtn	See also	Example

Determines where the image and text appear on a bitmap or speed button.

__property int Spacing = {read=FSpacing, write=SetSpacing, default=4};

Description

Spacing determines the number of pixels between the image (specified in the Glyph property) and the text (specified in the Caption property). The default value is 4 pixels.

If Spacing is a positive number, its value is the number of pixels between the image and text. If Spacing is 0, no pixels will be between the image and text. If Spacing is -1, the text appears centered between the image and the button edge. The number of pixels between the image and text is equal to the number of pixels between the text and the button edge opposite the glyph.


TBitBtn::Style

TBitBtn	See also	Example

Determines the appearance of a bitmap button.

enum TButtonStyle { bsAutoDetect, bsWin31, bsNew };

__property TButtonStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

The TButtonStyle type contains the values the Style property of bitmap buttons can assume. These are the possible values:

Value	Meaning

bsAutoDetect	When using Windows 3.x, the bitmap button uses the standard Windows 3.x look. When using a later version of Windows, the bitmap button uses a newer look.

bsWin31	Uses the standard Windows 3.1 look, regardless of which version of Windows is running.

bsNew	Uses a new bitmap button look, regardless of which version of Windows is running.


TBitBtn events

TBitBtn	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TBitBtn events

TBitBtn	By object	Legend

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TBitBtn methods

TBitBtn	Alphabetically

In TBitBtn

~TBitBtn

Click

TBitBtn

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBitBtn methods

TBitBtn	By object

~TBitBtn

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TBitBtn

Update

UpdateControlState


TBitBtn::Click

TBitBtn	See also

Simulates a mouse click, as if the user had clicked the button.

DYNAMIC void __fastcall Click(void);

Description

When Click is called any code attached to the OnClick event executes.

If the value of the Kind property is bkClose, calling Click closes the form. If the value of Kind is bkHelp, calling Click displays the Help screen assigned with the HelpContext property to the bitmap button. If Kind has any other value, the inherited Click method is called.


TBitBtn::TBitBtn

TBitBtn	See also

Constructs an instance of the button control and initializes its values.

__fastcall virtual TBitBtn(Classes::TComponent* AOwner);

__fastcall TBitBtn(HWND ParentWindow) : Stdctrls::TButton(ParentWindow) { }

Description

Call TBitBtn indirectly, using the new keyword, to programmatically instantiate a button. Buttons added in the form designer are created automatically.

Pass a single Component as a parameter to provide the Bit button with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the Bit button in a non-VCL window. This syntax is used when the button is implemented as an ActiveX control that is embedded in a non-VCL window.

TBitBtn

•	Calls the parent object's constructor method.

•	Creates the TBitmap for the Glyph property.

•	Assigns the GlyphChanged method to the OnChange event.

•	Creates a TCanvas object for the bitmap button.

•	Sets the Style property value to bsAutoDetect.

•	Sets the Kind property value to bkCustom.

•	Sets the Layout property value to blGlyphLeft.

•	Sets the Spacing property value to 4.

•	Sets the Margin property value to -1.


TBitBtn::~TBitBtn

TBitBtn	See also

Destroys the bitmap button object.

__fastcall virtual ~TBitBtn(void);

Description

Do not call ~TBitBtn directly in an application.  Instead, use the delete keyword.

~TBitBtn frees the TGlyph and TCanvas objects before calling the parent object's destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TButtonControl

TButton


TBitmap

Hierarchy	Properties	Methods	Events	See also

TBitmap is an encapsulation of a Windows bitmap (HBITMAP), including its palette (HPALETTE).

Unit

graphics

Description

TBitmap contains an internal image of the bitmap graphic and automatically manages realization of the palette when drawn. A bitmap is a powerful graphics object used to create, manipulate (scale, scroll, rotate, and paint), and store images in memory and as files on a disk.

To draw a bitmap on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TBitmap as a parameter.

Creating copies of a TBitmap is very fast since the handle is copied rather than the image. If the image is modified and the handle is shared by more than one TBitmap object, the image is copied before the modification is performed (that is, copy on write).


TBitmap properties

TBitmap	Alphabetically	Legend

In TBitmap

Canvas

Empty

Handle

HandleType

Height

IgnorePalette

MaskHandle

Monochrome

Palette

PixelFormat

ScanLine

TransparentColor

TransparentMode

Width

Derived from TGraphic

Modified

PaletteModified

Transparent


TBitmap properties

TBitmap	By object	Legend

Canvas

Empty

Handle

HandleType

Height

IgnorePalette

MaskHandle

Modified

Monochrome

Palette

PaletteModified

PixelFormat

ScanLine

Transparent

TransparentColor

TransparentMode

Width


TBitmap::Canvas

TBitmap	See also	Example

Provides access to a drawing surface that represents the bitmap.

__property TCanvas* Canvas = {read=GetCanvas};

Description

Canvas allows drawing on the bitmap by providing a TCanvas object for this purpose. Drawing on the canvas effectively modifies the underlying bitmap image pixels. Any canvas operation is valid on a bitmapnot just Draw and StretchDrawincluding line drawing, rectangles, and circles. The bitmap object is passed as a parameter to these methods.

A canvas object is created automatically for the bitmap and the property is read-only.


TBitmap::Empty

TBitmap	See also	Example

Specifies whether the bitmap object contains a bitmap.

__property bool Empty = {read=GetEmpty, nodefault};

Description

Use Empty to determine if a bitmap has been loaded into the bitmap object or drawn using its canvas property. Empty is false if the bitmap contains a bitmap image, and true if it does not.


TBitmap::Handle

TBitmap 	See also

Provides access to the Windows GDI bitmap handle for accessing the GDI bitmap object.

__property HBITMAP Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

Use Handle to call a Windows API function that requires the handle of a bitmap object. Pass Handle as the bitmap handle parameter to these functions.

Handle is the HBITMAP encapsulated by the bitmap object. Avoid grabbing the handle directly since it causes the HBITMAP to be copied if more than one TBitmap shares the handle.

Note:	Be careful who you give the handle to. If the receiver will take ownership (and destroy) the bitmap handle, call TBitmap::ReleaseHandle.


TBitmap::HandleType

TBitmap 	See also

Indicates whether the bitmap is a DDB, Device Dependent Bitmap, or a DIB, Device Independent Bitmap.

__property TBitmapHandleType HandleType = {read=GetHandleType, write=SetHandleType, nodefault};

Description

HandleType is used to find or modify the type of the bitmap. DDBs may be faster to draw on the screen, but may be stored in memory in a device-specific format. DIBs are stored in memory in a standard format supported by all devices (including printers).


TBitmap::Height

TBitmap	See also 	Example

Specifies the vertical size in pixels of the bitmap.

__property int Height = {read=GetHeight, write=SetHeight, nodefault};

Description

Use Height to find or set the height of the bitmap image. If the Height property is changed, the bitmap image is copied to a new image with the new Height. Any new area added to the bitmap is filled with white. If the new Height value is smaller than the current one, the bitmap image is cropped.


TBitmap::IgnorePalette

TBitmap	See also

Determines whether the bitmap realizes its palette when drawing its image.

__property bool IgnorePalette = {read=FIgnorePalette, write=FIgnorePalette, nodefault};

Description

Use IgnorePalette when speed of drawing is a priority. When IgnorePalette is true, the bitmap does not realize its palette when drawing itself, resulting in lower picture quality on 256-color video drivers, but faster drawing of the bitmap image.

Note:	C++Builder uses IgnorePalette only when a TDBImage is replicated in a TDBCtrlGrid.


TBitmap::MaskHandle

TBitmap 	See also

Provides access to the Windows GDI bitmap handle for accessing the GDI bitmap object.

__property HBITMAP MaskHandle = {read=GetMaskHandle, nodefault};

Description

Use MaskHandle to call a Windows API function that requires the handle of a bitmap object. Pass MaskHandle as the bitmap handle parameter to these functions.  MaskHandle is the HBITMAP encapsulated by the bitmap object's mask.


TBitmap::Monochrome

TBitmap	Example

Determines whether the bitmap displays its image in monochrome.

__property bool Monochrome = {read=GetMonochrome, write=SetMonochrome, nodefault};

Description

If Monochrome is true if the bitmap is a monochrome bitmap. Monochrome is false if the bitmap contains more than one bit per pixel.

Setting a color bitmap's Monochrome property to true changes the image to monochrome. Note that this operation is irreversible.


TBitmap::Palette

TBitmap

Controls a bitmap’s color mapping.

__property HPALETTE Palette = {read=GetPalette, write=SetPalette, nodefault};

Description

Use Palette to read or change the palette for a 256-color bitmap.

Palette is the HPALETTE realized by the bitmap.

When running in a 256-color video mode, and if the bitmap is drawn by an application running in the foreground, all colors of Palette are added to the Windows system palette. If the bitmap is drawn by an application running in the background and another application has loaded the system palette with its own colors, the bitmap's colors are mapped to the system palette. Palette=0 if the bitmap has no palette.

Another (although rare) use of Palette is to assign custom palettes created with CreatePalette to this property. Palette contains up to 256 colors that can be used to display the bitmap on screen.


TBitmap::PixelFormat

TBitmap 	See also

Indicates how the pixels of the bitmap image are stored in memory.

__property TPixelFormat PixelFormat = {read=GetPixelFormat, write=SetPixelFormat, nodefault};

Description

Use PixelFormat to set or change a TBitmap's internal image to a particular memory format and color depth, or to find out what memory format and color depth a TBitmap is using. This is most commonly used with ScanLine, because your code must decode the pixel data accessed by ScanLine. Image-editing tools usually use one pixel for all internal image operations and copy the results to the screen (in whatever format) as the last step.


 TBitmap::ScanLine

TBitmap	See also	Example

Provides indexed access to each line of pixels.

__property void * ScanLine[int Row] = {read=GetScanline};

Description

ScanLine is used only with DIBs (Device Independent Bitmaps) for image editing tools that do low-level pixel work.


TBitmap::TransparentColor

TBitmap	See also	Example

Determines which color of the bitmap is to be transparent when the bitmap is drawn.

__property TColor TransparentColor = {read=GetTransparentColor, write=SetTransparentColor, stored=TransparentColorStored, nodefault};

Description

Use TransparentColor to determine how to draw the bitmap transparently.  When the TransparentMode property is set to tmAuto (default), TransparentColor returns the color of the first pixel in the bitmap image data. For "bottom-up" bitmaps, the first pixel is the bottom leftmost pixel shown onscreen. For "top-down" bitmaps (less common), the first pixel is in the top left corner shown onscreen.

If TransparentColor is assigned-to, the TransparentMode is automatically set to tmFixed so that the new transparent color can be used later. If you want TransparentColor to disregard any assignments and return the bottom leftmost pixel color again, set TransparentMode to tmAuto.


TBitmap::TransparentMode

TBitmap	See also	Example

Determines whether the TransparentColor property's value is automatically calculated or stored with the bitmap object.

__property TTransparentMode TransparentMode = {read=FTransparentMode, write=SetTransparentMode, default=0};

Description

When TransparentMode is set to tmAuto, the TransparentColor property returns the color of the bottom-leftmost pixel of the bitmap image.  When TransparentMode is set to tmFixed, the TransparentColor property refers to the color stored in the bitmap object.


TBitmap::Width

TBitmap

Specifies the width in pixels of the bitmap.

__property int Width = {read=GetWidth, write=SetWidth, default=1};

Description

Use Width to find or set the width of the bitmap. Enlargements are filled with white. Shrinkage crops the image.


TBitmap events

TBitmap	Alphabetically

Derived from TGraphic

OnChange

OnProgress


TBitmap events

TBitmap	By object

OnChange

OnProgress


TBitmap methods

TBitmap	Alphabetically

In TBitmap

~TBitmap

Assign

Dormant

FreeImage

LoadFromClipboardFormat

LoadFromResourceID

LoadFromResourceName

LoadFromStream

Mask

ReleaseHandle

ReleaseMaskHandle

ReleasePalette

SaveToClipboardFormat

SaveToStream

TBitmap

Derived from TGraphic

LoadFromFile

SaveToFile

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBitmap methods

TBitmap	By object

~TBitmap

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Dormant

FieldAddress

Free

FreeImage

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromClipboardFormat

LoadFromFile

LoadFromResourceID

LoadFromResourceName

LoadFromStream

MethodAddress

MethodName

NewInstance

ReleaseHandle

ReleasePalette

SafeCallException

SaveToClipboardFormat

SaveToFile

SaveToStream

TBitmap


TBitmap::Assign

TBitmap	See also	Example

Copies a new bitmap image to the bitmap object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the bitmap handle of the Source bitmap to the bitmap object. Assign then calls the parent class' Assign. If the bitmap needs to be changed, the actual bitmap image is copied before the changes are made (copy on write).

Note	An object of one type can always be assigned to another object of the same type. Also, the Source can be of type TPicture if the Graphic property of the picture is a bitmap.


TBitmap::TBitmap

TBitmap	See also 	Example

Instantiates a bitmap object.

__fastcall virtual TBitmap(void);

Description

Call TBitmap to instantiate a bitmap object at runtime. TBitmap is also called automatically when a bitmap image is loaded into a TImage.

TBitmap allocates memory for a bitmap object, and calls the parent object's constructor. Then it creates a TBitmapImage as the internal image that represents the bitmap.


TBitmap::~TBitmap

TBitmap	See also

Disposes of the instance of the bitmap object.

__fastcall virtual ~TBitmap(void);

Description

Do not call ~TBitmap directly in an application. Instead, use the delete keyword to create a reference to a ~TBitmap object at runtime.


TBitmap::Dormant

TBitmap	See also	Example

Releases the canvas device context, if any, and forces the image into DIB format.

void __fastcall Dormant(void);

Description

Use Dormant to change the format of the bitmap in memory and possibly to save GDI resources. If the bitmap was a DDB, the DDB handle is released. DIB handles may use fewer Win95 GDI resources than DDB, but DIBs may also use more memory than DDBs, depending on the current video driver and mode.


TBitmap::FreeImage

TBitmap	Example

Frees the cached file image stored in memory by the bitmap.

void __fastcall FreeImage(void);

Description

Use FreeImage to reduce the memory requirements of an application when pixel format is not an issue. Freeing the image throws away the in-memory image loaded to disk originally. Therefore, you may lose the original pixel format of the bitmap (for example, if you changed its format to a DIB).

When a bitmap is loaded into a bitmap object, C++Builder creates an image of the loaded bitmap in memory. If the bitmap isn't changed, the memory image is used when saving the bitmap to verify that the bitmap has not changed the pixel format.


TBitmap::LoadFromClipboardFormat

TBitmap	See also 	Example

Loads a bitmap from the Clipboard into the bitmap object.

virtual void __fastcall LoadFromClipboardFormat(Word AFormat, int AData, HPALETTE APalette);

Description

LoadFromClipboardFormat is called if the bitmap is registered with the TPicture object using the RegisterClipboardFormat method.

LoadFromClipboardFormat replaces the current image with the data pointed to by the AData parameter. The palette for the bitmap is specified by the APalette parameter.


TBitmap::LoadFromResourceID

TBitmap	See also

Loads a bitmap from a resource into the bitmap object.

void __fastcall LoadFromResourceID(int Instance, int ResID);

Description

Use LoadFromResourceID to load a specified bitmap resource along with palette information from a module's executable file. The resource ID for the bitmap is specified in the ResID parameter.


TBitmap::LoadFromResourceName

TBitmap	See also	Example

Loads a bitmap resource into the bitmap object.

void __fastcall LoadFromResourceName(int Instance, const System::AnsiString ResName);

Description

LoadFromResourceName loads the specified bitmap resource along with palette information from a module's executable file. Specify the resource to be loaded as the value of ResName.

Note:	Use this routine to load bitmaps from RES files instead of the LoadBitmap API. LoadBitmap does not support 256-color images.


TBitmap::LoadFromStream

TBitmap	See also

Loads the bitmap from a stream into the bitmap object.

virtual void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Use LoadFromStream to load the bitmap image from a stream. The Stream parameter specifies the stream from which to read the bitmap image. For example, use LoadFromStream to load a bitmap image from a TBlobStream object that reads from a graphic field in a dataset.


TBitmap::Mask

TBitmap 	See also

Converts the current bitmap image into a monochrome mask, replacing TransparentColor with white and every other color with black.

void __fastcall Mask(TColor TransparentColor);

Description

Use Mask to produce a monochrome mask bitmap based on a given transparent color. Mask produces the same image that MaskHandle does, except that the resulting mask image replaces the image in the TBitmap object, so it only makes sense to call Mask once. Use MaskHandle when only a bitmap handle of the mask image is needed.


TBitmap::ReleaseHandle

TBitmap 	See also	Example

Returns the handle to the bitmap so that the TBitmap object no longer knows about the handle.

HBITMAP __fastcall ReleaseHandle(void);

Description

Use ReleaseHandle to disassociate the bitmap from the bitmap handle. Use it when you need to give a bitmap handle to a routine or object that will assume ownership (or destroy) the bitmap handle.


TBitmap::ReleaseMaskHandle

TBitmap 	See also

Returns the handle to the bitmap's mask so that the TBitmap object no longer knows about the mask handle.

HBITMAP __fastcall ReleaseMaskHandle(void);

Description

Use ReleaseMaskHandle to disassociate the bitmap object from the bitmap mask handle.


TBitmap::ReleasePalette

TBitmap

Returns the handle to the bitmap's palette and disassociates the palette from the TBitmap object.

HPALETTE __fastcall ReleasePalette(void);

Description

Use ReleasePalette to disassociate the palette from the bitmap image.


TBitmap::SaveToClipboardFormat

TBitmap	See also	Example

Creates a local copy of the bitmap in Clipboard format.

virtual void __fastcall SaveToClipboardFormat(Word &Format, int &Data, HPALETTE &APalette);

Description

Use SaveToClipboardFormat to copy the bitmap to a Clipboard format. The bitmap’s palette is returned in the APalette parameter, the format in the AFormat parameter, and a handle to the data in the AData parameter. Before the bitmap can be saved, an application must have registered the format with the TBitmap object using the RegisterClipboardFormat method.


TBitmap::SaveToStream

TBitmap 	See also

Saves the bitmap to a stream.

virtual void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Use SaveToStream to write the bitmap image to the stream specified by the Stream parameter. For example, specify a TBlobStream object as the Stream parameter to save the bitmap image to a graphic field in a dataset.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TGraphic


TBits

Hierarchy	Properties	Methods	See also

TBits stores an “array” of Boolean values.

Unit

classes

Description

Use TBits to store and access an indefinite number of boolean values. TBits can store as many boolean values as can fit in available memory, automatically expanding its storage space as needed. If the number of boolean values is limited to 32, the same functionality can be achieved using the bitwise & and | operators against a 32-bit integer variable.


TBits properties

TBits	Alphabetically

In TBits

Bits

Size


TBits properties

TBits	By object

Bits

Size


TBits::Bits

TBits	See also

Provides indexed access to the array of boolean values that the TBits object represents.

__property bool Bits[int Index] = {read=GetBit, write=SetBit};

Description

Use Bits to read or set a particular boolean value, as indexed by the Index parameter. If Index isn't in the range 0::::Size - 1, an EBitsError exception is thrown.


TBits::Size

TBits	See also

Represents the number of Boolean values the TBits object can hold.

__property int Size = {read=FSize, write=SetSize, nodefault};

Description

Set Size to expand or shrink the number of values in the array. When expanding the size, new entries are set to false. When shrinking the size, values whose indexes are less than or equal to the new size are preserved; entries whose indexes are greater than the new size are lost.


TBits methods

TBits	Alphabetically

In TBits

~TBits

OpenBit

TBits

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBits methods

TBits	By object

~TBits

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

OpenBit

SafeCallException

TBits


TBits::~TBits

TBits	See also

Destroys an instance of TBits.

__fastcall virtual ~TBits(void);

Description

Do not call ~TBits directly in an application. Instead, use the keyword delete, which takes an indirect referenct to a TBits object.

~TBits frees the memory used to store the array of boolean values.


TBits::OpenBit

TBits	See also

Returns the index of the first false value.

int __fastcall OpenBit(void);

Description

Use OpenBit to find the first bit in the array that has not been set to true.


TBits::TBits

TBits

Creates a new TBits object.

__fastcall virtual ~TBits(void);

Description

Do not call the TBits constructor directly. Instead, use the new keyword to create an indirect reference to a newly-constructed TBits instance.


Hierarchy

TObject


TBookmarkList

Hierarchy	Properties	Methods	See also

TBookmarkList is a collection of bookmarks that identify a set of records in a dataset.

Unit

dbgrids

Description

Use TBookmarkList to manage a set of bookmarks when working with the records in a dataset. Each bookmark identifies a particular record in the dataset, and can be identified by a string.


TBookmarkList properties

TBookmarkList	Alphabetically	Legend

In TBookmarkList

Count

CurrentRowSelected

Items


TBookmarkList properties

TBookmarkList	By object	Legend

Count

CurrentRowSelected

Items


TBookmarkList::Count

TBookmarkList	See also

Indicates the number of bookmarks in the bookmark list.

__property int Count = {read=GetCount, nodefault};

Description

Read Count to determine the number of entries in the Items array.  Use Count as an upper limit when iterating over the strings in the Items array.


TBookmarkList::CurrentRowSelected

TBookmarkList	See also

Indicates whether the Bookmark property of the associated DBGrid’s dataset is in the Items array.

__property bool CurrentRowSelected = {read=GetCurrentRowSelected, write=SetCurrentRowSelected, nodefault};

Description

Read CurrentRowSelected to determine whether the Bookmark property of the associated DBGrid’s dataset specifies a bookmark string in the Items property array. CurrentRowSelected is true when the bookmark string is included, false when it is not. The Bookmark property of the dataset indicates the current record in the dataset.

Set CurrentRowSelected to specify whether the Bookmark string of the associated DBGrid’s dataset should be included in the bookmark list.  Setting CurrentRowSelected to true adds the Bookmark property of the dataset to the Items array if it is not already there.  Setting CurrentRowSelected to false removes the Bookmark of the dataset from the Items array if it is there.  If the Bookmark property of the dataset is an empty string (no bookmark), setting CurrentRowSelected does nothing.

Note:	Trying to read or write CurrentRowSelected when the dataset is not active will throw an EInvalidGridOperation exception.


TBookmarkList::Items

TBookmarkList	See also

Provides indexed access to the bookmarks for marked records in the dataset.

__property System::AnsiString Items[int Index] = {read=GetItem};

Description

Use Items to obtain a bookmark string from the set maintained by the TBookmarkList object.  Each bookmark string represents a single record in the dataset of the associated DBGrid. Bookmark strings can be compared with other bookmark strings to determine relative position within the database, and used to position the dataset on an arbitrary record. The Index parameter indicates the index of the bookmark, where 0 is the index of the first bookmark, 1 is the index of the second bookmark, and so on.

Use Items with the Count property to iterate through all of the bookmarks in the list.

Note:	Bookmarks in the bookmark list are not automatically deleted when records in the dataset are deleted.  As a result, some bookmarks in the Items array may become invalid. Call the Refresh method to delete invalid bookmarks from the Items array.


TBookmarkList methods

TBookmarkList	Alphabetically

In TBookmarkList

~TBookmarkList

Clear

Delete

Find

IndexOf

Refresh

TBookmarkList

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBookmarkList methods

TBookmarkList	By object

~TBookmarkList

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

FieldAddress

Find

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

IndexOf

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Refresh

SafeCallException

TBookmarkList


TBookmarkList::Clear

TBookmarkList	See also

Deletes all bookmarks from the list.

void __fastcall Clear(void);

Description

Call Clear to empty the Items array and set the Count property to 0 when all rows of the associated DBGrid are deselected. Calling Clear invalidates the associated DBgrid so that the selected rows that were referenced by the bookmarks in the bookmark list can be repainted.

Note:	Clear removes the bookmarks from the bookmark list to reflect the fact that the corresponding rows are not selected. To delete the rows from the dataset rather than just deselecting them, call the Delete method instead.


TBookmarkList::TBookmarkList

TBookmarkList	See also

Creates an instance of TBookmarkList and associates it with a DBGrid.

__fastcall TBookmarkList(TCustomDBGrid* AGrid);

Description

Applications do not need to call create to instantiate the bookmark list used by DBGrids to implement their SelectedRows property.  DBGrids create the TBookmarkList object from their constructor.  Component writers that implement additional properties for descendants of TCustomDBGrid can create additional bookmark list objects to represent other sets of records in the dataset.


TBookmarkList::Delete

TBookmarkList	See also

Deletes all the records specified by the bookmarks in the list from the dataset of the associated DBGrid.

void __fastcall Delete(void);

Description

Call Delete to delete the set of records represented by the bookmark list from the dataset of the associated DBGrid.  To remove all the bookmarks from the list without changing the datset, use the Clear method instead.


TBookmarkList::~TBookmarkList

TBookmarkList	See also

Destroys an instance of TBookmarkList.

__fastcall virtual ~TBookmarkList(void);

Description

Do not call ~TBookmarkList directly in an application. Instead, use the delete keyword which takes an indirect reference to a bookmark list.

~TBookmarkList frees the memory used to store the Items property array.


TBookmarkList::Find

TBookmarkList	See also

Indicates whether a specified bookmark string is contained in the bookmark list.

bool __fastcall Find(const System::AnsiString Item, int &Index);

Description

Call Find to determine whether the string specified by the Item parameter is one of the bookmark strings in the Items property array.  Find returns true if the bookmark list contains the bookmark string, false otherwise.  If Find returns true, the index of the bookmark string is returned as the value of the Index parameter.

Note:	The index of a specific bookmark string can also be obtained by using the IndexOf method.  Unlike the IndexOf method, which returns a value of -1 if the bookmark string is not in the Items array, Find does not change the value of the Index parameter if the bookmark string can’t be found.  Use Find when a default value should be changed only if the bookmark is not in the list.


TBookmarkList::IndexOf

TBookmarkList	See also

Returns the index of a bookmark string in the Items property array.

int __fastcall IndexOf(const System::AnsiString Item);

Description

Call IndexOf to get the index for a bookmark string in the Items array. The first item in the array has index 0, the second item has index 1, and so on. If an item is not in the list, IndexOf returns -1.


 TBookmarkList::Refresh

TBookmarkList	See also

Removes all invalid bookmarks from the Items property array.

bool __fastcall Refresh(void);

Description

Bookmarks in the bookmark list are not automatically deleted when records in the dataset are deleted.  As a result, some bookmarks in the Items array may become invalid. Call Refresh to ensure that every bookmark in the bookmark list is valid.  Refresh attempts to locate every record in the dataset that corresponds to a bookmark in the Items property array. All bookmarks that do not correspond to records in the dataset are removed.

If any of the bookmarks in the list are invalid, Refresh returns true, and invalidates the DBGrid so that it will repaint, reflecting the removal of all invalid records.  If all bookmarks in the list are still valid,  Refresh returns false.


Accessibility

Read-only


Hierarchy

TObject


TBlobField

Hierarchy	Properties	Methods	Events	See also

TBlobField represents a field in a dataset that holds a reference to a binary large object (BLOB).

Unit

db

Description

BLOB fields are database fields that contain binary data of arbitrary length. Unlike binary fields, BLOB fields do not store the binary data directly in the database table. Instead, the field in the physical database table contains a reference to a separate file that contains the individual BLOB value for the field.

TBlobField introduces new methods to support streaming of the data in the BLOB field.

As a descendant of TField, TBlobField includes many properties, methods, and events that are useful for managing the value and properties of a field in a database.

BLOB field components can represent different arbitrarily large data types. These data types are distinguished in the header of the binary data. In addition to the field types supported directly, TBlobField is the direct ancestor of two BLOB field components: TMemoField (ftMemo) and TGraphicField (ftGraphic).


TBlobField properties

TBlobField	Alphabetically	Legend

In TBlobField

AsString

AsVariant

BlobSize

BlobType

IsNull

Modified

Transliterate

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TBlobField properties

TBlobField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

BlobSize

BlobType

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Modified

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

Transliterate

ValidChars

Value

VCLComObject

Visible


TBlobField::AsString

TBlobField	See also

Represents the value of the BLOB field as an AnsiString.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to assign the BLOB field value to a string or to assign a string value to the BLOB field.

For example, this code assigns a string value to a BLOB field value:

MyBLOBField->AsString = "Assign the string to a BLOB field";

To assign a BLOB field value to a string value, use code similar to this:

BlobString = MyBLOBField->AsString;

Typically, using AsString makes sense only if the BLOB contains text, such as that in a memo field component. The AnsiString type can, however, store binary data as well. Thus, even BLOB fields for nontextual BLOB types such as ftGraphic or ftTypedBinary can use the AsString property.

Use the AsString property rather than the Text property to set the BLOB field’s value to textual data. Trying to set the Text property will throw an exception.


TBlobField::AsVariant

TBlobField	See also

Represents the value of the BLOB field as a variant value.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the BLOB field value to a variant variable.

•	Assign a variant value to the BLOB field.

Using variants is useful when you don't know the actual field type and don't want to use one of the other As... properties to convert the field value to another type.


TBlobField::BlobSize

TBlobField	See also

Indicates the number of bytes of data contained in the blob field on the current record.

__property int BlobSize = {read=GetBlobSize, nodefault};

Description

Read BlobSize to determine the amount of memory required to store the contents of the BLOB field. Use BlobSize instead of the DataSize property, which always returns 0 for BLOB fields.

Note:	Unlike the DataSize property, which specifies the size for field data on any record, BlobSize gives the size of the BLOB data for the current record only.


TBlobField::BlobType

TBlobField	See also

Identifies the type of the BLOB field associated with a BLOB field object.

__property TBlobType BlobType = {read=GetBlobType, write=SetBlobType, nodefault};

Description

Use BlobType to set or read the data type for the BLOB data associated with the field component.

Specify BlobType when using a TBlobField object to represent a BLOB field type that isn’t directly supported (such as a formatted memo BLOB). The BlobType ensures that the BLOB type in the table matches the expected field type.

TBlobType is a range of TFieldType values. These are the values in that range:

Value	Description

ftBlob	Binary Large Object field

ftMemo	Text memo field

ftGraphic	Bitmap field

ftFmtMemo	Formatted text memo field

ftParadoxOle	Paradox OLE field

ftDBaseOle	dBase OLE field

ftTypedBinary	Typed binary field


TBlobField::IsNull

TBlobField	See also

Indicates whether the BLOB field contains any data.

__property bool IsNull = {read=GetIsNull, nodefault};

Description

Read IsNull to determine whether the BLOB field is blank. IsNull is true if the BLOB field is empty. IsNull is false if the BLOB field contains any data.


TBlobField::Modified

TBlobField	See also

Indicates whether a the value for the BLOB field was changed since it was last read from disk.

__property bool Modified = {read=GetModified, write=SetModified, nodefault};

Description

Set Modified to true when changing the value to a BLOB field using direct Borland Database Engine (BDE) API calls. If the value of the BLOB field is set by using the properties of TBlobField, or by using a TBlobStream object, Modified is automatically set to true.

BLOB fields use the Modified property to trigger data events and to indicate when the BDE needs to clean up the buffers used to store BLOB data.


TBlobField::Transliterate

TBlobField	See also

Determines whether any text in the BLOB field should be converted between the ANSI character set and the character set identified by the dataset.

__property bool Transliterate = {read=FTransliterate, write=FTransliterate, nodefault};

Description

Use Transliterate when the physical database table identified by the dataset does not use an ANSI language driver and the data may contain extended ASCII characters.

When Transliterate is true, BLOB fields call the AnsiToNative function to translate the ANSI characters to the character set used by the dataset when the value is changed using the Value property, the AsString property, or the AsVariant property. When these properties are read to obtain the value of the BLOB field, the NativeToAnsi function translates the characters in the database table to the ANSI character set.

Note:	TBlobStream objects also check the Transliterate property when reading from or writing to a BLOB field.


TBlobField::Value

TBlobField	See also

Represents the data in the BLOB field.

__property System::AnsiString Value = {read=GetAsString, write=SetAsString};

Description

Use Value to read data directly from and write data directly to a BLOB field component at runtime. For BLOB fields, the Value property is equivalent to the AsString property.

Note:	The AnsiString type can store binary data as well as text. Thus, even BLOB fields for nontextual BLOB types such as ftGraphic or ftTypedBinary can get or set their data using an AnsiString.


TBlobField events

TBlobField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TBlobField events

TBlobField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TBlobField methods

TBlobField	Alphabetically

In TBlobField

~TBlobField

Assign

Clear

IsBlob

LoadFromFile

LoadFromStream

SaveToFile

SaveToStream

SetFieldType

SetText

TBlobField

Derived from TField

AssignValue

FocusControl

GetData

IsValidChar

RefreshLookupList

SetData

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBlobField methods

TBlobField	By object

~TBlobField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SaveToFile

SaveToStream

SetData

SetFieldType

SetText

TBlobField

Validate


TBlobField::Assign

TBlobField	See also

Copies a value to the BLOB field.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to copy data to the BLOB field. Assign copies the Value of a BLOB field from

•	Another BLOB field

•	A TStrings object

•	A TBitmap object, if the BlobType is ftGraphic or ftTypedBinary

•	A TPicture object, if the BlobType is ftGraphic or ftTypedBinary

•	Any object that supports TBlobField in its AssignTo method


TBlobField::Clear

TBlobField	See also

Clears the current value in the BLOB field.

virtual void __fastcall Clear(void);

Description

Use Clear to delete the current value in the field and leave the field without a value.


TBlobField::TBlobField

TBlobField	See also

Creates an instance of a BLOB field component.

__fastcall virtual TBlobField(Classes::TComponent* AOwner);

Description

Do not call the constructor for TBlobField directly. Instead, use the new keyword, which returns an indirect reference to a newly constructed BLOB field. Explicit construction of TBlobField objects is seldom needed because the BLOB field component is instantiated automatically for all BLOB fields in a dataset.

TBlobField sets the DataType to ftBlob after calling the parent object's constructor.


TBlobField::IsBlob

TBlobField	See also 	Example

Indicates that this is a BLOB field.

virtual bool __fastcall IsBlob() { IsBlob(__classid(TBlobField));

Description

Use IsBlob when working with a TField object to determine whether it represents BLOB data. For example, before using the GetData or SetData method (which does not work with BLOB fields), call IsBlob to determine whether the method can be used. The IsBlob method for TBlobField always returns true.


TBlobField::LoadFromFile

TBlobField	See also

Loads a BLOB from a file into the field.

void __fastcall LoadFromFile(const System::AnsiString FileName);

Description

Use LoadFromFile to load the contents of a file into a BLOB field. Specify the name of the file to load into the field as the value of the FileName parameter.


TBlobField::LoadFromStream

TBlobField	See also

Loads a BLOB from a stream into the field.

void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Use LoadFromStream to copy the contents of a stream into the BLOB field. Specify the stream from which the field’s value is copied as the value of the Stream parameter.


TBlobField::SaveToFile

TBlobField	See also

Saves the contents of the BLOB field to a file.

void __fastcall SaveToFile(const System::AnsiString FileName);

Description

Use SaveToFile to save the contents of the BLOB field to a file. Specify the name of the file as the value of the FileName parameter.


TBlobField::SaveToStream

TBlobField	See also

Saves the contents of the BLOB field to a stream.

void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Use SaveToStream to copy the contents of a BLOB field to a stream. Specify the name of the stream to which the field’s value is saved as the value of the Stream parameter.


TBlobField::SetFieldType

TBlobField	See also

Specifies the type of the BLOB field.

virtual void __fastcall SetFieldType(TFieldType Value);

Description

Use SetFieldType to change the field type of a BLOB field, overriding the default type.

Normally, the type of the physical database field is checked and a TFieldType is selected that matches most closely. BLOB fields can indicate more explicitly what kind of BLOB is in the database. Specify the BLOB type as the value of the Value parameter.

These following table contains the possible values for BLOB fields. Calling SetFieldType with any other data type does nothing.

Value	Description

ftBlob	Binary Large Object field

ftMemo	Text memo field

ftGraphic	Bitmap field

ftFmtMemo	Formatted text memo field

ftParadoxOle	Paradox OLE field

ftDBaseOle	dBase OLE field

ftTypedBinary	Typed binary field

Note:	Calling SetFieldType does the same thing as setting the BlobType property.


TBlobField::SetText

TBlobField	See also

Throws an exception for BLOB field objects.

virtual void __fastcall SetText(const System::AnsiString Value);

Description

SetText prevents data-aware controls from storing the "(fieldname) " string back into the dataset. To set the value of a BLOB field to textual data, use the AsString property.


TBlobField::~TBlobField

TBlobField

Frees the memory associated with the TBlobField object.

__fastcall virtual ~TBlobField(void) { }

Description

Do not call ~TBlobField directly. Instead, use the delete keyword on the object, which causes ~TBlobField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField


TBlobStream

Hierarchy	Properties	Methods	See also

TBlobStream is a stream object that provides services which allow applications to read from or write to field objects that represent Binary large object (BLOB) fields.

Unit

dbtables

Description

Use TBlobStream to access or modify the value of a BLOB field object. BLOB field objects are TBlobField objects and descendants of TBlobField such as TGraphicField and TMemoField. BLOB fields use BLOB streams to implement many of their data access properties and methods.

TBlobStream allows objects that have no specialized knowledge of how data is stored in a BLOB field to read or write such data by employing the uniform stream interface.

To use a BLOB stream, create an instance of TBlobStream, use the methods of the stream to read or write the data, and then free the BLOB stream. Do not use the same instance of TBlobStream to access data from more than one record. Instead, create a new TBlobStream object every time you need to read or write BLOB data on a new record.


TBlobStream properties

TBlobStream	Alphabetically	Legend

Derived from TStream

Position

Size


TBlobStream properties

TBlobStream	By object	Legend

Position

Size


TBlobStream methods

TBlobStream	Alphabetically

In TBlobStream

~TBlobStream

Read

Seek

TBlobStream

Truncate

Write

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBlobStream methods

TBlobStream	By object

~TBlobStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

Seek

TBlobStream

Truncate

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TBlobStream::TBlobStream

TBlobStream	See also 	Example

Creates an instance of TBlobStream.

__fastcall TBlobStream(Db::TBlobField* Field, Db::TBlobStreamMode Mode);

Description

Do not call TBlobStream directly. Instead, use the new keyword when creating BLOB streams at runtime. Create instances of TBlobStream for reading from or writing to a specific TBlobField object.

TBlobStream links the TBlobStream to the field object specified by the Field parameter. Mode specifies how the stream will be used. Mode must be one of the following values:

Value	Meaning

bmRead	The BLOB stream can read data from the field.

bmWrite	The BLOB stream can replace the data in the field.

bmReadWrite	The BLOB stream can modify the data in the field.


TBlobStream::~TBlobStream

TBlobStream	See also

Destroys an instance of TBlobStream.

__fastcall virtual ~TBlobStream(void);

Description

Do not call ~TBlobStream directly in an application. Instead use the delete keyword, which takes an indirect reference to a TBlobStream object.

~TBlobStream triggers an OnDataChange event if the BLOB stream was used to overwrite or modify the data in the field. ~TBlobStream then frees any buffers that were allocated to handle the data.


TBlobStream::Read

TBlobStream	See also 	Example

Reads up to Count bytes from the current position in the field’s data into Buffer.

virtual int __fastcall Read(void *Buffer, int Count);

Description

Call Read to read data from the BLOB field when the number of bytes in the field’s data is not known. Buffer must have at least Count bytes allocated to hold the data that was read from the field.

Read transfers up to Count bytes from the BLOB data into Buffer, starting in the current position, and then advances the current position by the number of bytes actually transferred. Read returns the number of bytes actually transferred (which may be less than the number requested in Count)

Read checks the Transliterate property of the field, and converts the data into ANSI from the character set specified by the dataset if Transliterate is true.

All the other data-reading methods of a BLOB stream (ReadBuffer, ReadComponent) call Read to do their actual reading.

Note:	Do not call Read when the TBlobStream was created in bmWrite mode.


TBlobStream::Seek

TBlobStream	See also 	Example

Resets the current position of the TBlobStream object.

virtual int __fastcall Seek(int Offset, Word Origin);

Description

Use Seek to move the current position within the BLOB data by the indicated offset. Seek allows an application to read from or write to a particular location within the BLOB data.

The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value	Meaning

soFromBeginning	Offset is from the beginning of the BLOB data. Seek moves to the position Offset. Offset must be >= 0.

soFromCurrent	Offset is from the current position in the BLOB data. Seek moves to Position + Offset.

soFromEnd	Offset is from the end of the BLOB data. Offset must be <= 0 to indicate a number of bytes before the end of the BLOB.

Seek returns the new value of the Position property, the new current position in the BLOB data.


TBlobStream::Truncate

TBlobStream	See also 	Example

Discards all data in the BLOB field from the current position on.

void __fastcall Truncate(void);

Description

Use Truncate to limit the size of the BLOB data. Calling Truncate when the current position is 0 will clear the contents of the BLOB field.

Note:	Do not call Truncate when the TBlobStream was created in bmRead mode.


TBlobStream::Write

TBlobStream	See also 	Example

Writes Count bytes from Buffer to the current position in the field and updates the current position by Count bytes.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Use Write to write Count bytes to the BLOB field, starting at the current position. The Write method for TBlobStream always writes the entire Count bytes, as BLOB data does not necessarily include a termination character. Thus, Write is equivalent to the WriteBuffer method.

Write checks the Transliterate property of the field, and converts the data from ANSI into the character set of the dataset if Transliterate is true.

All the other data-writing methods of a BLOB stream (WriteBuffer, WriteComponent) call Write to do their actual writing.

Note:	Do not call Write when the TBlobStream was created in bmRead mode.


Accessibility

Read-only


Hierarchy

TObject

TStream


TBitmapImage

Hierarchy	Methods	See also

TBitmapImage is the internal representation of the bitmap image for a TBitmap object.

Unit

graphics

Description

TBitmapImage is used only for internal implementation in C++Builder.  It represents the internal image of the  bitmap encapsulated by the TBitmap object.  All of the data and methods introduced in TBitmapImage are private.  They contain information about the specific HBITMAP, including pointers to the standard HBITMAP structures defined by Windows. TBitmapImage is referenced in the constructor of the TBitmap object when the bitmap image is created.

Note	TBitmapImage is how TBitmap does reference counting and handle sharing. Multiple instances can refer to the same TBitmap image. TBitmapImage is the actual owner of the bitmap handle.


TBitmapImage methods

TBitmapImage	Alphabetically

In TBitmapImage

~TBitmapImage

TBitmapImage

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBitmapImage methods

TBitmapImage	By object

~TBitmapImage

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TBitmapImage


TBitmapImage::TBitmapImage

TBitmapImage

Creates a new TBitmapImage object.

__fastcall virtual TBitmapImage(void);

Description

Do not call TBitmapImage directly. Instead, use the new keyword to create a reference to a TBitmapImage object at runtime.


TBitmapImage::~TBitmapImage

TBitmapImage

Frees the memory associated with the TBitmapImage object.

__fastcall virtual ~TBitmapImage(void);

Description

Do not call ~TBitmapImage directly. Instead, use the delete keyword.


Hierarchy

TObject

TSharedImage


TBooleanField

Hierarchy	Properties	Methods	Events	See also

TBooleanField represents a field containing Boolean values.

Unit

db

Description

Boolean fields can hold values of true or false.

TBooleanField introduces new properties to convert between boolean values and other data types, and to provide display strings that represent various interpretations of the data. As a descendant of TField, TBooleanField includes many properties, methods, and events that are useful for managing the value and properties of a field in a database.


TBooleanField properties

TBooleanField	Alphabetically	Legend

In TBooleanField

AsBoolean

AsString

AsVariant

DataSize

DisplayValues

Value

Derived from TField

Alignment

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TBooleanField properties

TBooleanField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayValues

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TBooleanField::AsBoolean

TBooleanField	See also

Represents the value of a Boolean field as a boolean value.

__property bool AsBoolean = {read=GetAsBoolean, write=SetAsBoolean, nodefault};

Description

Use AsBoolean to set or get the value of a Boolean field using the bool type. Physical Boolean database fields store boolean values as 16-bit boolean values. AsBoolean converts between the 16-bit boolean value and the bool type.


TBooleanField::AsString

TBooleanField	See also

Represents the value of a Boolean field as an AnsiString.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to

•	Assign the Boolean field value to an AnsiString.

•	Assign an AnsiString value to the Boolean field.

For example, this code assigns a string value to an Boolean field value:

MyBoolField->AsString = "True";

To assign a Boolean field value to an AnsiString variable, use code similar to this:

StringVar = MyBoolField->AsString;

If the DisplayValues property has not been set, when a Boolean value is inserted or updated using the AsString property, the value is set to true if the string is "True", and false if the string is "False". Any other string throws an EDatabaseError exception.

The DisplayValues property specifies the strings associated with the values of true or false. Change the DisplayValues property to change the strings that must be assigned to set the value of the Boolean field to true or false.

Reading the AsString property returns the string that corresponds to the value of the field. If DisplayValues has not been set, this is "True" or "False".


TBooleanField::AsVariant

TBooleanField	See also

Represents the value of a Boolean field as a variant value.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the Boolean field value to variant variable.

•	Assign a variant value to the Boolean field.

Using variants is useful when both the actual field type and the type of the data is unknown.


TBooleanField::DataSize

TBooleanField	See also 	Example

Indicates the amount of memory needed to store the value of a Boolean field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a Boolean field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods. GetData and SetData work with the field’s value in native database format.

For Boolean fields, DataSize is always 2, because database tables use a 16-bit boolean type to store boolean values. This type is not the same as the bool type used by TBooleanField to store and manipulate boolean values.


TBooleanField::DisplayValues

TBooleanField	See also

Controls how the Boolean field is translated to and from display format.

__property System::AnsiString DisplayValues = {read=FDisplayValues, write=SetDisplayValues};

Description

Use DisplayValues to specify strings you want used to represent Boolean values. Use any pair of phrases, separated by a semicolon. For example, to have the true and false values correspond to the letters T and F, respectively, set DisplayValues to

T;F

Similarly, to set the values of true and false to the strings Yes and No, set DisplayValues to

Yes;No

The string associated with true or false can be an empty string. To set the value for true to an empty string, set DisplayValues to a string that begins with a semicolon. For example, to associate false with the string Fail, and true with an empty string, set DisplayValues to

;Fail

To associate false with an empty string, set DisplayValues to the string for true, with no semicolon at all.

The strings associated with true and false by DisplayValues appear in data-aware controls when they display the data for a Boolean field. If one of the strings is an empty string, boolean values associated with that string appear blank in data-aware controls.

These strings are also used when getting or setting the Boolean field’s AsString property.


TBooleanField::Value

TBooleanField	See also

Represents the value of the data in the Boolean field.

__property bool Value = {read=GetAsBoolean, write=SetAsBoolean, nodefault};

Description

Use Value to read data from and write data to a Boolean field object at runtime. Using Value is the same as using the AsBoolean property. Use Value when you know the field component is a Boolean field. Use AsBoolean when working with a generic field component.


TBooleanField events

TBooleanField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TBooleanField events

TBooleanField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TBooleanField methods

TBooleanField	Alphabetically

In TBooleanField

~TBooleanField

TBooleanField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBooleanField methods

TBooleanField	By object

~TBooleanField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TBooleanField

Validate


TBooleanField::TBooleanField

TBooleanField	See also

Instantiates a Boolean field object.

__fastcall virtual TBooleanField(Classes::TComponent* AOwner);

Description

Do not call TBooleanField directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated Boolean field object. It is seldom necessary to explicitly create Boolean fields because a Boolean field object is instantiated automatically for all Boolean fields in a dataset.

After calling the parent object's constructor, TBooleanField sets the DataType to ftBoolean, and initializes the strings associated with Boolean values to "True" and "False".


TBooleanField::~TBooleanField

TBooleanField

Frees the memory associated with the TBooleanField object.

__fastcall virtual ~TBooleanField(void) { }

Description

Do not call ~TBooleanField directly. Instead, use the delete keyword on the object, which causes ~TBooleanField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField


TBrush

Hierarchy	Properties	Methods	Events

TBrush represents the color and pattern used to fill solid shapes.

Unit

graphics

Description

TBrush encapsulates the Winodws brush object (HBRUSH) and is used to fill solid shapes, such as rectangles and ellipses, with a color or pattern.


TBrush properties

TBrush	Alphabetically	Legend

In TBrush

Bitmap

Color

Handle

Style

Derived from TGraphicsObject

OwnerCriticalSection


TBrush properties

TBrush	By object	Legend

Bitmap

Color

Handle

OwnerCriticalSection

Style


TBrush::Bitmap

TBrush	See also 	Example

An external bitmap image that defines a pattern for the brush.

__property TBitmap* Bitmap = {read=GetBitmap, write=SetBitmap};

Description

Bitmap points to a TBitmap object that holds a BMP image. If Bitmap is nonempty, the brush’s pattern is defined by the BMP image (rather than the Style property). If the image is larger than eight pixels by eight pixels, only the top left eight-by-eight region is used.

Changing the image does not affect the brush until the TBitmap is reassigned to the Bitmap property. Be sure to free the TBitmap after finishing with the brush, since TBrush will not free it.


TBrush::Color

TBrush	See also 	Example

The color of the brush.

__property TColor Color = {read=GetColor, write=SetColor, default=16777215};

Description

The Color property determines the color of the brush.  This is the color that is used to draw the pattern represented by the Style property, not the background color of the brush (unless Style is bsSolid).

Note

If the value of the Style property is bsClear, the Color property is ignored. Further, any value assigned to the Color property is lost when Style is set to bsClear.


TBrush::Handle

TBrush

The Windows handle for the brush.

__property HBRUSH Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

The Handle property provides access to the Windows GDI object handle.


TBrush::Style

TBrush	See also 	Example

The pattern for the brush.

__property TBrushStyle Style = {read=GetStyle, write=SetStyle, default=0};

Description

The Style property determines the pattern painted by the brush, unless a value is assigned to Bitmap. The possible values of Style are

Value	Pattern	Value	Pattern

bsSolid	bsCross

bsClear	bsDiagCross

bsBDiagonal	bsHorizontal

bsFDiagonal	bsVertical


TBrush events

TBrush	Alphabetically

Derived from TGraphicsObject

OnChange


TBrush events

TBrush	By object

OnChange


TBrush methods

TBrush	Alphabetically

In TBrush

~TBrush

Assign

TBrush

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TBrush methods

TBrush	By object

~TBrush

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TBrush


TBrush::Assign

TBrush	See also

Copies the contents of the brush to another brush.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the brush’s properties from another TBrush instance.


TBrush::TBrush

TBrush

Creates and initializes a TBrush instance.

__fastcall TBrush(void);

Description

Do not call TBrush directly. Instead, use the keyword new, which returns an indirect reference to the new TBrush object.


TBrush::~TBrush

TBrush	See also

Destroys the TBrush instance and frees its memory.

__fastcall virtual ~TBrush(void);

Description

Do not call ~TBrush directly in an application. Do not call ~TBruch directly. Instead, use the delete keyword on the object, which causes ~TBrush to be invoked automatically.


Scope

Published


Hierarchy

TObject

TPersistent

TGraphicsObject


TButtonControl

Hierarchy	Properties	Methods	See also

TButtonControl is the base class for objects that represent Windows button controls.

Unit

stdctrls

Description

Use TButtonControl as a base class when defining a standard Windows-style button.  Do not create instances of TButtonControl directly in an application.  Instead, use a descendant of TButtonControl to put a push button, check box, or radio button on a form.

Note:	Some buttons, such as TSpeedButton, do not use the built-in Windows button controls. These controls do not descend from TButtonControl.


TButtonControl properties

TButtonControl	Alphabetically	Legend

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TButtonControl properties

TButtonControl	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ControlCount

ControlState

Controls

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TButtonControl methods

TButtonControl	Alphabetically	Legend

In TButtonControl

~TButtonControl

TButtonControl

WndProc

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TButtonControl methods

TButtonControl	By object	Legend

~TButtonControl

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TButtonControl

Update

UpdateControlState

WndProc


TButtonControl::WndProc

TButtonControl	See also

Handles Windows messages.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc enables button objects to receive input focus when WM_LBUTTONDOWN and WM_LBUTTONDBLCLK messages occur.


TButtonControl::TButtonControl

TButtonControl

Creates a new TButtonControl object.

__fastcall virtual TButtonControl(Classes::TComponent* AOwner) : Controls::TWinControl(AOwner) { }

__fastcall TButtonControl(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not create instances of TButtonControl. It is intended only as a base class.

The first constructor syntax, with a single component as a parameter, provides the button with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. The second constructor syntax, with a window handle as a parameter, embeds the button in a non-VCL window. This syntax is used when the button is implemented as an ActiveX control that is embedded in a non-VCL window.


TButtonControl::~TButtonControl

TButtonControl

Frees the memory associated with the TButtonControl object.

__fastcall virtual ~TButtonControl(void) { }

Description

Do not call ~TButtonControl directly. Instead, use the delete keyword on the object, which causes ~TButtonControl to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TButtonControl example

TButtonControl


 TButton

Hierarchy	Properties	Methods	Events	See also

TButton is a push button control.

Unit

stdctrls

Description

Use TButton to put a standard Windows push button on a form.  TButton introduces several properties to control its behavior in a dialog box setting.  Users choose button controls to initiate actions.

To use a button that displays a bitmap instead of a label, use TBitBtn.  To use a button that can remain in a depressed position, use TSpeedButton.


TButton properties

TButton	Alphabetically	Legend

In TButton

Cancel

Default

ModalResult

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TButton properties

TButton	By object	Legend

Align

BoundsRect

Brush

Cancel

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

Default

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

Left

ModalResult

Name

Owner

Parent

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TButton::Cancel

TButton	See also	Example

Determines whether the button’s OnClick event handler executes when the Escape key is pressed.

__property bool Cancel = {read=FCancel, write=FCancel, default=0};

Description

If Cancel is true, the button’s OnClick event handler executes when the user presses Esc. Although an application can have more than one Cancel button, the form calls the OnClick event handler only for the first visible button in the tab order.


TButton::Default

TButton	See also

Determines whether the button’s OnClick event handler executes when the Enter key is pressed.

__property bool Cancel = {read=FCancel, write=FCancel, default=0};

Description

If Default is true, the button’s OnClick event handler executes when the user presses Enter.

Although an application can have more than one Default button, the form calls the OnClick event handler only for the first visible button in the tab order. Moreover, any button that has focus becomes the Default button temporarily; hence, if the user selects another button before pressing Enter, the selected button’s OnClick event handler executes instead.


TButton::ModalResult

TButton	See also

Determines whether and how the button closes its (modal) parent form.

typedef int TModalResult;

__property Forms::TModalResult ModalResult = {read=FModalResult, write=FModalResult, default=0};

Description

Setting the TButton component’s ModalResult property is an easy way to make clicking the button close a modal form. When a button is clicked, the ModalResult property of its parent form is set to the same value as the button’s ModalResult property.

For example, if a dialog box has OK and Cancel buttons, their ModalResult properties could be set at design time to mrOk and mrCancel, repectively. At runtime, clicking the OK button would then change the dialog’s ModalResult property to mrOk, and clicking the Cancel button would change the dialog’s ModalResult property to mrCancel. Unless further processing is required, there is no need to write OnClick event handlers for the buttons.


TButton events

TButton	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TButton events

TButton	By object	Legend

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TButton methods

TButton	Alphabetically

In TButton

~TButton

Click

TButton

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TButton methods

TButton	By object

~TButton

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TButton

Update

UpdateControlState


TButton::Click

TButton	See also

Simulates a mouse click, as if the user had clicked the button.

DYNAMIC void __fastcall Click(void);

Description

Calling Click assigns the value of the button’s ModalResult property to the ModalResult property of its parent form, and then generates an OnClick event.


TButton::TButton

TButton	See also

Creates and initializes a TButton instance.

__fastcall virtual TButton(Classes::TComponent* AOwner);

__fastcall TButton(HWND ParentWindow) : Stdctrls::TButtonControl(ParentWindow) { }

Description

Use TButton indirectly, using the new keyword, to programmatically instantiate a button. Buttons added to forms at design time are created automatically.

Pass a single Component as a parameter to provide the button with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the button in a non-VCL window. This syntax is used when the button is implemented as an ActiveX control that is embedded in a non-VCL window.

TButton

•	Calls the parent object's constructor method.

•	Sets the ControlStyle of the button to include the values csSetCaption, csOpaque, csDoubleClicks.

•	Sets Width to 75 pixels, and Height to 25 pixels.

•	Sets the TabStop property to true.


TButton::~TButton

TButton

~TButton frees the memory associated with the TButton object.

__fastcall virtual ~TButton(void) { }

Description

Do not call ~TButton directly. Instead, use the delete keyword on the object, which causes ~TButton to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TButtonControl


TBytesField

Hierarchy	Properties	Methods	Events	See also

TBytesField represents a bytes field in a dataset.

Unit

db

Description

A bytes field value is a set of unformatted bytes of fixed size.

TBytesField introduces no new properties, events, or methods. It overrides the DataSize property and constructor to reflect the specifics of a field of type ftBytes.


TBytesField properties

TBytesField	Alphabetically	Legend

In TBytesField

DataSize

Derived from TBinaryField

AsString

AsVariant

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TBytesField properties

TBytesField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TBytesField::DataSize

TBytesField	See also 	Example

Indicates the amount of memory needed to store the value of a Bytes field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a Bytes field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For Bytes fields, DataSize is the same as the Size property.


TBytesField events

TBytesField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TBytesField events

TBytesField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TBytesField methods

TBytesField	Alphabetically

In TBytesField

~TBytesField

TBytesField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TBytesField methods

TBytesField	By object

~TBytesField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TBytesField

Validate


TBytesField::TBytesField

TBytesField	See also

Creates an instance of TBytesField.

__fastcall virtual TBytesField(Classes::TComponent* AOwner);

Description

Do not call TBytesField directly. Instead, use the new keyword which returns an indirect reference to a newly instantitated TBytesField object. It is seldom necessary to explicitly instantiate a TBytesField object because datasets automatically instantiate their field objects.

After calling the parent object's constructor, TBytesField sets the DataType to ftBytes.


TBytesField::~TBytesField

TBytesField

Frees the memory associated with the TBytesField object.

__fastcall virtual ~TBytesField(void) { }

Description

Do not call ~TBytesField directly. Instead, use the delete keyword on the object, which causes ~TBytesField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TBinaryField


ECacheError

Hierarchy	Properties	Methods	See also

ECacheError is the exception class for failures that occur when building the cache of a decision cube.

Unit

mxstore

Description

ECacheError is thrown when

•	The dataset for a decision cube includes too many fields.

•	The dataset for a decision cube does not include the necessary summaries for computing a derived value such as an average.

•	A dimension item in the dimension map specifies a date range for dimension that does not represent a date or date-time field.


ECacheError properties

ECacheError	Alphabetically

Derived from Exception

HelpContext

Message


ECacheError properties

ECacheError	By object

HelpContext

Message


ECacheError methods

ECacheError	Alphabetically

In ECacheError

~ECacheError

ECacheError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ECacheError methods

ECacheError	By object

~ECacheError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ECacheError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ECacheError::ECacheError

ECacheError	See also

ECacheError creates a new ECacheError object.

__fastcall ECacheError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall ECacheError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall ECacheError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall ECacheError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall ECacheError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall ECacheError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ECacheError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall ECacheError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

ECacheError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ECacheError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


ECacheError::~ECacheError

ECacheError	See also

~ECacheError frees the memory associated with the ECacheError object.

__fastcall virtual ~ECacheError(void) { }

Description

Do not call ~ECacheError directly. Instead, use the delete keyword on the object, which causes ~ECacheError to be invoked automatically.


Hierarchy

TObject

Exception


ECacheError example

ECacheError


TCanvas

Hierarchy	Properties	Methods	Events	See also

TCanvas provides an abstract drawing space for objects that must render their own images.

Unit

graphics

Description

Use TCanvas as a drawing surface for objects that draw an image of themselves. Standard window controls such as edit controls or list boxes do not require a canvas, as they are drawn by Windows.

TCanvas provides properties, events and methods that assist in creating an image by

•	Specifying the type of brush, pen and font to use.

•	Drawing and filling a variety of shapes and lines.

•	Writing text.

•	Rendering graphic images.

•	Enabling a response to changes in the current image.

TCanvas has two descendants, TControlCanvas and TMetafileCanvas, which assist in drawing images of controls and in creating metafile images for objects.


TCanvas properties

TCanvas	Alphabetically	Legend

In TCanvas

Brush

ClipRect

CopyMode

Font

Handle

LockCount

Pen

PenPos

Pixels


TCanvas properties

TCanvas	By object	Legend

Brush

ClipRect

CopyMode

Font

Handle

LockCount

Pen

PenPos

Pixels


TCanvas::Brush

TCanvas	See also	Example

Determines the color and pattern for filling graphical shapes and backgrounds.

__property TBrush* Brush = {read=FBrush, write=SetBrush};

Description

Set the Brush property to specify the color and pattern to use when drawing the background or filling in graphical shapes. The value of Brush is a TBrush object. Set the properties of the TBrush object to specify the color and pattern or bitmap to use when filling in spaces on the canvas.

Note:	Setting the Brush property assigns the specified TBrush object, rather than replacing the current TBrush object.


TCanvas::ClipRect

TCanvas	See also

Specifies the boundaries of the clipping rectangle.

__property Windows::TRect ClipRect = {read=GetClipRect};

Description

Use ClipRect to limit the drawing region of the canvas. Any drawing that occurs at coordinates outside the ClipRect is clipped and doesn’t appear in the image. For example, to draw a portion of a large circle in a smaller box, first draw the box, then set the ClipRect to the rectangle defined by the inner boundary of the box. Drawing the entire circle will only show the portion that is within the box.

When handling a form’s OnPaint event, the canvas' ClipRect property is set to the rectangle that needs to be painted. Portions of the image that do not overlap the ClipRect do not need to be drawn. Thus, OnPaint routines can use the value of ClipRect to optimize painting and speed the overall performance of the application.


TCanvas::CopyMode

TCanvas	See also	Example

Specifies how the a graphical image is copied onto the canvas.

__property int CopyMode = {read=FCopyMode, write=FCopyMode, default=13369376};

Description

Set CopyMode to affect the way graphical images are drawn onto the canvas. The CopyMode is used when copying an image from another canvas using the CopyRect method. The CopyMode is also used by TBitmap objects when they draw themselves to a canvas.

Use CopyMode to achieve a variety of affects when rendering an image. Achieve special effects like merged images and making parts of a bitmap transparent by combining multiple images with different CopyModes.

The following table shows the possible values of CopyMode. (These are constants defined in the Windows.hpp)

Value	Meaning

cmBlackness	Fills the destination rectangle on the canvas with black.

cmDstInvert	Inverts the image on the canvas and ignores the source.

cmMergeCopy	Combines the image on the canvas and the source bitmap by using the Boolean AND operator.

cmMergePaint	Combines the inverted source bitmap with the image on the canvas by using the Boolean OR operator.

cmNotSrcCopy	Copies the inverted source bitmap to the canvas.

cmNotSrcErase	Combines the image on the canvas and the source bitmap by using the Boolean OR operator, and inverts the result.

cmPatCopy	Copies the source pattern to the canvas.

cmPatInvert	Combines the source pattern with the image on the canvas using the Boolean XOR operator

cmPatPaint	Combines the inverted source bitmap with the source pattern by using the Boolean OR operator. Combines the result of this operation with the image on the canvas by using the Boolean OR operator.

cmSrcAnd	Combines the image on the canvas and source bitmap by using the Boolean AND operator.

cmSrcCopy	Copies the source bitmap to the canvas.

cmSrcErase	Inverts the image on the canvas and combines the result with the source bitmap by using the Boolean AND operator.

cmSrcInvert	Combines the image on the canvas and the source bitmap by using the Boolean XOR operator.

cmSrcPaint	Combines the image on the canvas and the source bitmap by using the Boolean OR operator.

cmWhiteness	Fills the destination rectangle on the canvas with white.


TCanvas::Font

TCanvas	See also

Specifies the font to use when writing text on the image.

__property TFont* Font = {read=FFont, write=SetFont};

Description

Set Font to specify the font to use for writing text on the image. The value of Font is a TFont object. Set the properties of the TFont object to specify the font face, color, size, and style of the font.

Note:	Setting the Font property assigns the specified TFont object, rather than replacing the current TFont object.


TCanvas::Handle

TCanvas	See also

Specifies the Windows GDI handle to the device context for this canvas.

__property HDC Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

Set Handle to the HDC for the device context the canvas must draw into. When a windowed control responds to a Windows paint message, the HDC for drawing is passed in to the PaintWindow method. In other cases, an HDC can be obtained for a window by calling the GetDeviceContext method of a control. Additionally, Windows provides API calls to obtain an HDC for a printer or for a memory image.

Read the Handle property to supplement the drawing services provided by the TCanvas object with API calls that require a handle to a device context. Most of the Windows GDI calls require an HDC.

TCanvas does not own the HDC. Applications must create an HDC and set the Handle property. Applications must release the HDC when it is no longer needed by the canvas. Setting the Handle property of a canvas that already has a valid HDC will not automatically release the initial HDC.

Note:	Some descendants of TCanvas, such as TControlCanvas, do own the HDC. Do not set the Handle property for these objects. They fetch and free their own Handle.


TCanvas::LockCount

TCanvas	See also

Indicates the number of times the canvas has been locked to prevent interference from other threads.

__property int LockCount = {read=FLockCount, nodefault};

Description

Read LockCount to determine whether the canvas is locked. Whenever the Lock method is called to block other threads from interfering with the canvas, LockCount increases. Whenever the Unlock method is called at the end of a critical section, LockCount decreases. When LockCount is 0, other threads may draw on the canvas.


TCanvas.Pen
TCanvas::Pen

TCanvas	See also 	Example

Specifies the kind of pen the canvas uses for drawing lines and outlining shapes.

__property TPen* Pen = {read=FPen, write=SetPen};

Description

Set Pen to specify the pen to use for drawing lines and outlining shapes in the image. The value of Pen is a TPen object. Set the properties of the TPen object to specify the color, style, width, and mode of the pen.

Note:	Setting the Pen property assigns the specified TPen object, rather than replacing the current TPen object.


TCanvas::PenPos

TCanvas	See also

Specifies the current drawing position of the Pen.

__property tagPOINT PenPos = {read=GetPenPos, write=SetPenPos};

Description

Read PenPos to learn the current drawing position of the Pen. This is the starting point of a line drawn by the LineTo method. Setting the PenPos property is equivalent to calling the MoveTo method.


TCanvas::Pixels

TCanvas	See also 	Example

Specifies the color of the pixels within the current ClipRect.

__property TColor Pixels[int X][int Y] = {read=GetPixel, write=SetPixel};

Description

Read Pixels to learn the color on the drawing surface at a specific pixel position. Write Pixels to change the color of individual pixels on the drawing surface. Use Pixels for detailed effects on an image. Pixels may also be used to determine the color that should be used for the FillRect method.

Not every device context supports the Pixels property. Reading the Pixels property for such a device context will return a value of -1. Setting the Pixels property for such a device context does nothing.

Note:	The Pixels property is only valid for pixels within the current value of ClipRect.


TCanvas events

TCanvas	Alphabetically

In TCanvas

OnChange

OnChanging


TCanvas events

TCanvas	By object

OnChange

OnChanging


TCanvas::OnChange

TCanvas	See also

Occurs when the image has just changed.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action whenever the image on the canvas changes. When an application calls one of the drawing methods of TCanvas, the following steps occur.

1	An OnChanging event occurs.

2	The TCanvas method makes a change to the image.

3	An OnChange event occurs.

OnChange events occur on changes to the image, not changes to the properties of the canvas. Applications can respond to changes in the Font, Brush, and Pen properties by assigning OnChange event handlers to the corresponding TFont, TBrush, and TPen objects. However, TCanvas assigns its own OnChange event handlers for those objects. Before assigning an OnChange event handler to one of these objects, read the existing event handler. Use that value to call the TCanvas event handler from the new event handler.


TCanvas::OnChanging

TCanvas	See also

Occurs just before a change is made to the image.

__property Classes::TNotifyEvent OnChanging = {read=FOnChanging, write=FOnChanging};

Description

Write an OnChanging event handler to take specific action before the image on the canvas changes. When an application calls one of the drawing methods of TCanvas, the following steps occur.

1	An OnChanging event occurs.

2	The TCanvas method makes a change to the image.

3	An OnChange event occurs.


TCanvas methods

TCanvas	Alphabetically

In TCanvas

~TCanvas

Arc

BrushCopy

Chord

CopyRect

Draw

DrawFocusRect

Ellipse

FillRect

FloodFill

FrameRect

LineTo

Lock

MoveTo

Pie

PolyBezier

PolyBezierTo

Polygon

Polyline

Rectangle

Refresh

RoundRect

StretchDraw

TCanvas

TextExtent

TextHeight

TextOut

TextRect

TextWidth

TryLock

Unlock

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCanvas methods

TCanvas	By object

~TCanvas

Arc

Assign

BrushCopy

Chord

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyRect

DefaultHandler

Dispatch

Draw

DrawFocusRect

Ellipse

FieldAddress

FillRect

FloodFill

FrameRect

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LineTo

Lock

MethodAddress

MethodName

MoveTo

NewInstance

Pie

PolyBezier

PolyBezierTo

Polygon

Polyline

Rectangle

Refresh

RoundRect

SafeCallException

StretchDraw

TCanvas

TextExtent

TextHeight

TextOut

TextRect

TextWidth

TryLock

Unlock


TCanvas.Arc

TCanvas	See also 	Example

Draws an arc on the image along the perimeter of the ellipse bounded by the specified rectangle.

void __fastcall Arc(int X1, int Y1, int X2, int Y2, int X3, int Y3, int X4, int Y4);

Description

Use Arc to draw an elliptically curved line with the current Pen. The arc traverses the perimeter of an ellipse that is bounded by the points (X1,Y1) and (X2,Y2). The arc is drawn following the perimeter of the ellipse, counterclockwise, from the starting point to the ending point. The starting point is defined by the intersection of the ellipse and a line defined by the center of the ellipse and (X3,Y3). The ending point is defined by the intersection of the ellipse and a line defined by the center of the ellipse and (X4, Y4).

Note:	On Windows 95, the sums X1 + X2 and Y1 + Y2 cannot exceed 32768. Also, the sum X1 + X2 + Y1 + Y2 cannot exceed 32768.

On NT, the drawing direction can be changed to clockwise using the Windows API call SetArcDirection.


TCanvas::BrushCopy

TCanvas	See also 	Example

Copies a portion of a bitmap onto a rectangle on the canvas, replacing one of the colors of the bitmap with the brush of the canvas.

void __fastcall BrushCopy(const Windows::TRect &Dest, TBitmap* Bitmap, const Windows::TRect &Source, TColor Color);

Description

Use BrushCopy to achieve special effects such as making the copied image partially transparent. BrushCopy is provided mainly for backwards compatibility. Use a TImageList instead of BrushCopy.

Dest specifies the rectangular portion of the canvas that will receive the copy of the bitmap. Bitmap specifies the graphic to copy from. Source specifies the rectangular area of Bitmap to copy. Color specifies the color in Bitmap to replace with the Brush of the canvas.

To use BrushCopy to make the copied image partially transparent, specify the color of the surface of the canvas (clBackground for example) as the Color of the Brush property, then call BrushCopy.


TCanvas::Chord

TCanvas	See also	Example

Draws a closed figure represented by the intersection of a line and an ellipse.

void __fastcall Chord(int X1, int Y1, int X2, int Y2, int X3, int Y3, int X4, int Y4);

Description

Use Chord to create a shape that is defined by an arc and a line that joins the endpoints of the arc. The chord consists of a portion of an ellipse that is bounded by the points (X1,Y1) and (X2,Y2). The ellipse is bisected by a line that runs between the points (X3,Y3) and (X4,Y4).

The perimeter of the chord runs counter clockwise from (X3, Y3), counterclockwise along the ellipse to (X4,Y4), and straight back to (X3,Y3). If (X3,Y3) and (X4,Y4) are not on the surface of the ellipse, the corresponding corners on the chord are the closest points on the perimeter that intersect the line. The outline of the chord is drawn using the value of Pen, and the shape is filled using the value of Brush.

Note:	On Windows 95, the sums X1 + X2 and Y1 + Y2 cannot exceed 32768. Also, the sum X1 + X2 + Y1 + Y2 cannot exceed 32768.

On NT, the drawing direction can be changed to clockwise using the Windows API call SetArcDirection.


TCanvas::CopyRect

TCanvas	See also 	Example

Copies part of an image from another canvas into the canvas.

void __fastcall CopyRect(const Windows::TRect &Dest, TCanvas* Canvas, const Windows::TRect &Source);

Description

Use CopyRect to transfer part of the image on another canvas to the image of the TCanvas object. Dest specifies the rectangle on the canvas where the source image will be copied. The Canvas parameter specifies the canvas with the source image. Source specifies a rectangle bounding the portion of the source canvas that will be copied.

The portion of the source canvas is copied using the mode specified by CopyMode.


TCanvas::TCanvas

TCanvas	See also

Creates an instance of TCanvas.

__fastcall TCanvas(void);

Description

Do not call the TCanvas constructor directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated canvas. TCanvas allocates memory for the instance of TCanvas and creates the TFont, TBrush and TPen objects for the Font, Brush, and Pen properties. TCanvas also initializes the CopyMode to cmSrcCopy.


TCanvas::~TCanvas

TCanvas	See also

Destroys an instance of TCanvas.

__fastcall virtual ~TCanvas(void);

Description

Do not call ~TCanvas directly in an application. Instead, use the delete keyword, which takes an indirect reference to a TCanvas instance.

~TCanvas frees the TBrush, TFont, and TPen objects that were created for the Brush, Font, and Pen properties. ~TCanvas then frees the memory for the TCanvas object.


TCanvas::Draw

TCanvas 	See also 	Example

Renders the graphic specified by the Graphic parameter on the canvas at the location given by the coordinates (X, Y).

void __fastcall Draw(int X, int Y, TGraphic* Graphic);

Description

Call Draw to draw a graphic on the canvas. Draw calls the Draw method of the graphic. The image is rendered into a rectangle determined by the size of the graphic, with the upper left corner at the point (X, Y).

Graphics can be bitmaps, icons, or metafiles. If the graphic is a TBitmap object, the bitmap is rendered using the value of CopyMode.


TCanvas::DrawFocusRect

TCanvas	See also 	Example

Draws a rectangle in the style used to indicate that the object inside the rectangle has focus.

void __fastcall DrawFocusRect(const Windows::TRect &Rect);

Description

Call DrawFocusRect for the perimeter of the image of a control when the control gets or loses input focus. Because DrawFocusRect uses an XOR function, calling it a second time while specifying the same rectangle removes the rectangle from the screen.

The rectangle this function draws cannot be scrolled. To scroll an area containing a rectangle drawn by DrawFocusRect, call DrawFocusRect to remove the rectangle from the screen, scroll the area, and then call DrawFocusRect to draw the rectangle in the new position.


TCanvas::Ellipse

TCanvas	See also 	Example

Draws the ellipse defined by a bounding rectangle on the canvas.

void __fastcall Ellipse(int X1, int Y1, int X2, int Y2);

Description

Call Ellipse to draw a circle or ellipse on the canvas. The top left point of the bounding rectangle is at pixel coordinates (X1, Y1) and the bottom right point is at (X2, Y2). If the points of the rectangle form a square, a circle is drawn.

The ellipse is outlined using the value of Pen, and filled using the value of Brush.

Note:	On Windows 95, the sums X1 + X2 and Y1 + Y2 cannot exceed 32768. Also, the sum X1 + X2 + Y1 + Y2 cannot exceed 32768.


TCanvas::FillRect

TCanvas	See also 	Example

Fills the specified rectangle on the canvas using the current brush.

void __fastcall FillRect(const Windows::TRect &Rect);

Description

Use FillRect to fill a rectangular region using the current brush. The region is filled including the top and left sides of the rectangle, but excluding the bottom and left edges.


TCanvas::FloodFill

TCanvas	See also	Example

Fills an area of the canvas using the current brush.

void __fastcall FloodFill(int X, int Y, TColor Color, TFillStyle FillStyle);

Description

Use FloodFill to fill a possibly non-rectangular region of the image with the value of Brush. The boundaries of the region to be filled are determined by moving outward from the point (X,Y) until a color boundary involving the Color parameter is encountered.

FillStyle determines what type of color changes define the boundaries, as indicated in the following table.

Value	Meaning

fsSurface	Fill all area that has the color indicated by the Color parameter. Stop when another color is encountered.

fsBorder	Fill all area that does not have the color indicated by the Color parameter. Stop when Color is encountered.

Use the Pixels property to get the exact value of the color at the point (X,Y) when using a FillStyle of fsSurface. Similarly, when FillStyle is fsBorder, use Pixels to get the exact value of the boundary color if a point on the boundary is known.


TCanvas::FrameRect

TCanvas	See also 	Example

Draws a rectangle using the Brush of the canvas to draw the border.

void __fastcall FrameRect(const Windows::TRect &Rect);

Description

Use FrameRect to draw a 1 pixel wide border around a rectangular region. FrameRect does not fill the interior of the rectangle with the Brush pattern.

To draw a boundary using the Pen instead, use the Polygon method.


TCanvas::LineTo

TCanvas	See also 	Example

Draws a line on the canvas from PenPos to the point specified by X and Y, and sets the pen position to (X, Y).

void __fastcall LineTo(int X, int Y);

Description

Use LineTo to draw a line from PenPos up to, but not including the point (X,Y). LineTo changes the value of PenPos to (X,Y).

The line is drawn using Pen.


TCanvas::Lock

TCanvas	See also

Prevents other threads from drawing on the canvas.

void __fastcall Lock(void);

Description

Call Lock in a multithreaded application to prevent other threads from drawing on the canvas. Lock prevents other cooperating threads in the application from executing until the Unlock method is called. Nested calls to Lock increment the LockCount property so that the canvas is not unlocked until the last lock is released.

In multi-threaded applications that use Lock to protect a canvas, all calls that use the canvas must be protected by a call to Lock.  Any thread that does not lock the canvas before using it will introduce potential bugs.

Because Lock prevents other threads from executing, it can adversely affect performance. Do not call Lock unless there is a danger that another thread might interfere with drawing on the canvas.


TCanvas::MoveTo

TCanvas	See also 	Example

Changes the current drawing position to the point (X,Y).

void __fastcall MoveTo(int X, int Y);

Description

Use MoveTo to set the value of PenPos before calling LineTo. Calling MoveTo is equivalent to setting the PenPos property.


TCanvas.Pie
TCanvas::Pie

TCanvas	See also	Example

Draws a pie-shaped the section of the ellipse bounded by the rectangle (X1, Y1) and (X2, Y2) on the canvas.

void __fastcall Pie(int X1, int Y1, int X2, int Y2, int X3, int Y3, int X4, int Y4);

Description

Use Pie to draw a pie-shaped wedge on the image. The wedge is defined by the ellipse bounded by the rectangle determined by the points (X1, Y1) and X2, Y2). The section drawn is determined by two lines radiating from the center of the ellipse through the points (X3, Y3) and (X4, Y4).

The wedge is outlined using Pen, and filled using Brush.

Note:	On Windows 95, the sums X1 + X2 and Y1 + Y2 cannot exceed 32768. Also, the sum X1 + X2 + Y1 + Y2 cannot exceed 32768.


TCanvas::PolyBezier

TCanvas	See also

Draws a set of Bézier curves.

void __fastcall PolyBezier(const tagPOINT * Points, const int Points_Size);

Description

Use PolyBezier to draw cubic Bézier curves using the endpoints and control points specified by the Points parameter. The first curve is drawn from the first point to the fourth point, using the second and third points as control points. Each subsequent curve in the sequence needs exactly three more points: the ending point of the previous curve is used as the starting point, the next two points in the sequence are control points, and the third is the ending point.

This procedure draws lines by using the current pen.

Use the Slice function to pass a portion of an array of points to the PolyBezier method. For example, to form a Bézier curve using the first ten points from an array of 100 points, use the Slice function as follows:

Canvas->PolyBezier(Slice(PointArray, 10));


TCanvas::PolyBezier
TCanvas::PolyBezierTo

TCanvas	See also

Draws a set of Bézier curves and updates the value of PenPos.

void __fastcall PolyBezierTo(const tagPOINT * Points, const int Points_Size);

Description

Use PolyBezierTo to draw cubic Bézier curves by using the endpoints and control points specified by the Points parameter. The first curve is drawn from the first point to the fourth point, using the second and third points as control points. Each subsequent curve in the sequence needs exactly three more points: the ending point of the previous curve is used as the starting point, the next two points in the sequence are control points, and the third is the ending point.

This procedure draws lines by using the current pen and updates the value of PenPos to the value of the last endpoint.

Use the Slice function to pass a portion of an array of points to the PolyBezierTo method. For example, to form a Bézier curve using the first ten points from an array of 100 points, use the Slice function as follows:

Canvas->PolyBezierTo(Slice(PointArray, 10));


TCanvas::Polygon

TCanvas	See also 	Example

Draws a series of lines on the canvas connecting the points passed in and closing the shape by drawing a line from the last point to the first point.

void __fastcall Polygon(const tagPOINT * Points, const int Points_Size);

Description

Use Polygon to draw a closed, many-sided shape on the canvas, using the value of Pen. After drawing the complete shape, Polygon fills the shape using the value of Brush.

To draw a polygon on the canvas, without filling it, use the Polyline method, specifying the first point a second time at the end.

Use the Slice function to pass a portion of an array of points to the Polygon method. For example, to form a polygon from the first ten points from an array of 100 points, use the Slice function as follows:

Canvas->Polygon(Slice(PointArray, 10));


TCanvas::Polyline

TCanvas	See also 	Example

Draws a series of lines on the canvas with the current pen, connecting each of the points passed to it in Points.

void __fastcall Polyline(const tagPOINT * Points, const int Points_Size);

Description

Use Polyline to connect a set of points on the canvas. If there are only two points, Polyline draws a single line.

Calling the MoveTo function with the value of the first point, and then repeatedly calling LineTo with all subsequent points will draw the same image on the canvas. However, unlike LineTo, Polyline does not change the value of PenPos.

Use the Slice function to pass a portion of an array of points to the Polyline method. For example, to connect the first ten points in an array of 100 points, use the Slice function as follows:

Canvas->Polyline(Slice(PointArray, 10));


TCanvas::Rectangle

TCanvas	See also 	Example

Draws a rectangle on the canvas with its upper left corner at the point (X1, Y1) and its lower right corner at the point (X2, Y2).

void __fastcall Rectangle(int X1, int Y1, int X2, int Y2);

Description

Use Rectangle to draw a rectangle using Pen and fill it with Brush. To fill a rectangular region without drawing the boundary in the current pen, use FillRect. To outline a rectangular region without filling it, use FrameRect or Polygon. To draw a rectangle with rounded corners, use RoundRect.


TCanvas::Refresh

TCanvas	See also

Deselects the Pen, Brush, and Font from the device context.

void __fastcall Refresh(void);

Description

Call Refresh to return the HDC used by the canvas to a default state. Refresh does not change the values of the Font, Brush, or Pen properties. Calling any of the drawing methods of the canvas after calling Refresh will re-select the Font, Brush, or Pen into the HDC if it is used by the drawing method.


TCanvas::RoundRect

TCanvas	See also 	Example

Draws a rectangle with rounded corners on the canvas.

void __fastcall RoundRect(int X1, int Y1, int X2, int Y2, int X3, int Y3);

Description

Use RoundRect to draw a rounded rectangle using Pen and fill it with Brush. The rectangle will have edges defined by the points (X1,Y1), (X2,Y1), (X2,Y2), (X1,Y2), but the corners will be shaved to create a rounded appearance. The curve of the rounded corners matches the curvature of an ellipse with width X3 and height Y3.

To draw an ellipse instead, use Ellipse. To draw a true rectangle, use Rectangle.


TCanvas::StretchDraw

TCanvas	See also	Example

Draws the graphic specified by the Graphic parameter in the rectangle specified by the Rect parameter.

void __fastcall StretchDraw(const Windows::TRect &Rect, TGraphic* Graphic);

Description

Call StretchDraw to draw a graphic on the canvas so that the image fits in the specified rectangle. StretchDraw calls the Draw method of the graphic. The graphic object determines how to fit into the rectangle. This may involve changing magnification and/or aspect ratio.

To render the graphic in its natural size, use the Draw method, instead.

Graphics can be bitmaps, icons, or metafiles. If the graphic is a TBitmap object, the bitmap is rendered using the value of CopyMode.


TCanvas::TextExtent

TCanvas	See also

Returns the width and height, in pixels, of a string rendered in the current font.

tagSIZE __fastcall TextExtent(const System::AnsiString Text);

Description

Use TextExtent to determine the space a string will occupy in the image. Other elements in the image such as lines, boxes, or additional lines of text can be positioned to accommodate the size of the text.

To check only the height, call TextHeight. To check only the width, call TextWidth.


TCanvas::TextHeight

TCanvas	See also 	Example

Returns the height, in pixels, of a string rendered in the current font.

int __fastcall TextHeight(const System::AnsiString Text);

Description

Use TextHeight to determine the height a string will occupy in the image. Other elements in the image such as lines, boxes, or additional lines of text can be positioned to accommodate the height of the text.

TextHeight returns the same value as TextExtent(Text).cy.


TCanvas::TextOut

TCanvas	See also 	Example

Writes a string on the canvas, starting at the point (X,Y), and then updates the PenPos to the end of the string.

void __fastcall TextOut(int X, int Y, const System::AnsiString Text);

Description

Use TextOut to write a string onto the canvas. The string will be written using the current value of Font. Use the TextExtent method to determine the space occupied by the text in the image. To write only the text that fits within a clipping rectangle, use TextRect instead.


TCanvas::TextRect

TCanvas	See also 	Example

Writes a string inside a clipping rectangle.

void __fastcall TextRect(const Windows::TRect &Rect, int X, int Y, const System::AnsiString Text);

Description

Use TextRect to write a string within a limited rectangular region. Any portions of the string that fall outside the rectangle passed in the Rect parameter are clipped and don't appear. The upper left corner of the text is placed at the point (X, Y).


TCanvas::TextWidth

TCanvas	See also 	Example

Returns the width, in pixels, of a string rendered in the current font.

int __fastcall TextWidth(const System::AnsiString Text);

Description

Use TextWdith to determine the length a string will occupy in the image. TextWidth indicates whether a given string will fit in the available space. Other graphical elements in the image such as lines, or additional strings can be positioned to accommodate the width of the text.

TextWidth returns the same value as TextExtent(Text).cx.


TCanvas::TryLock

TCanvas	See also

Locks the canvas if it is currently unlocked.

bool __fastcall TryLock(void);

Description

Call TryLock to prevent other threads from writing on the surface of the canvas until the Unlock method is called. Unlike calls to the Lock method, which nest so that every call to Lock must be matched with a subsequent call to Unlock, TryLock need only be matched by a call to Unlock if the canvas was not already locked.

If the canvas is unlocked, Trylock locks the canvas, sets the LockCount property to 1, and returns true. If the canvas is already locked, Trylock returns false without making any changes.

Use TryLock before attempting changes to the canvas that could interfere with other code that is protected by a Lock ... Unlock pair of method calls.


TCanvas::Unlock

TCanvas	See also

Decreases the LockCount property, allowing other threads to execute when LockCount reaches 0.

void __fastcall Unlock(void);

Description

Call Unlock at the end of a critical section begun with a call to the Lock method. Every call to Lock must be matched by a call to Unlock.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent


TCustomDecisionGraph

Hierarchy	Properties	Methods	Events	See also

TCustomDecisionGraph is the base class for controls that graph crosstabulated data.

Unit

mxgraph

Description

Use TCustomDecisionGraph as a base class when defining objects that graph the data from a decision source. Decision graphs chart a single summary that is calculated over a number of dimensions. The dimensions appear as axes of the graph.

The field that is summarized and the fields (dimensions) over which it is summarized can be changed dynamically at runtime to view any configuration of summary and dimensions chosen from the dimension map of a decision cube. Changes to the dimensions and summary can be initiated using a TDecisionPivot object.

Do not create instances of TCustomDecisionGraph. To put a decision graph on a form, use TDecisionGraph.


TCustomDecisionGraph properties

TCustomDecisionGraph	Alphabetically	Legend

In TCustomDecisionGraph

DecisionSource

Derived from TChart

AllowPanning

AllowZoom

AnimatedZoom

AnimatedZoomSteps

BackImage

BackImageInside

BackImageMode

BottomWall

Foot

Gradient

LeftWall

PrintResolution

Title

Zoomed

Derived from TCustomChart

AxisVisible

BackColor

BottomAxis

BufferedDisplay

Chart3DPercent

ClipPoints

Frame

LeftAxis

Legend

MarginBottom

MarginLeft

MarginRight

MarginTop

MaxPointsPerPage

Monochrome

Page

RightAxis

ScaleLastPage

Series

SeriesList

TopAxis

View3d

View3dWalls

Derived from TCustomTeePanel

Canvas

Derived from TCustomPanel

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

Locked

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomDecisionGraph properties

TCustomDecisionGraph	By object	Legend

Align

AllowPanning

AllowZoom

AnimatedZoom

AnimatedZoomSteps

AxisVisible

BackColor

BackImage

BackImageInside

BackImageMode

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

BottomAxis

BottomWall

BoundsRect

Brush

BufferedDisplay

Canvas

Chart3DPercent

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ClipPoints

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DecisionSource

DesignInfo

DragCursor

DragMode

Enabled

Foot

Frame

Gradient

Handle

Height

HelpContext

Hint

Left

LeftAxis

LeftWall

Legend

Locked

MarginBottom

MarginLeft

MarginRight

MarginTop

MaxPointsPerPage

Monochrome

Name

Owner

Page

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

PrintResolution

RightAxis

ScaleLastPage

Series

SeriesList

ShowHint

Showing

TabOrder

TabStop

Tag

Title

Top

TopAxis

VCLComObject

View3d

View3dWalls

Visible

Width

WindowProc

Zoomed


TCustomDecisionGraph::DecisionSource

TCustomDecisionGraph

Specifies the decision source object that supplies data values for the decision graph.

__property Mxdb::TDecisionSource* DecisionSource = {read=GetDecisionSource, write=SetDecisionSource};

Description

Set DecisionSource to link the decision graph to the crosstabulated data from a decision cube. The DecsionSource object maintains information about the current pivot state of the data. Thus, any two decision controls that share the same decision source will display the data from the decision cube using the same configuration of dimensions, including any closed dimensions or drilled down values.


TCustomDecisionGraph events

TCustomDecisionGraph	Alphabetically	Legend

Derived from TChart

OnAllowScroll

OnClickAxis

OnClickBackground

OnClickLegend

OnClickSeries

OnGetLegendPos

OnGetLegendRect

OnScroll

OnUndoZoom

OnZoom

Derived from TCustomChart

OnAfterDraw

OnGetAxisLabel

OnGetLegendText

OnGetNextAxisLabel

OnPageChange

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp


TCustomDecisionGraph events

TCustomDecisionGraph	By object	Legend

OnAfterDraw

OnAllowScroll

OnClick

OnClickAxis

OnClickBackground

OnClickLegend

OnClickSeries

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnGetAxisLabel

OnGetLegendPos

OnGetLegendRect

OnGetLegendText

OnGetNextAxisLabel

OnMouseDown

OnMouseMove

OnMouseUp

OnPageChange

OnResize

OnScroll

OnUndoZoom

OnZoom


TCustomDecisionGraph methods

TCustomDecisionGraph	Alphabetically

In TCustomDecisionGraph

~TCustomDecisionGraph

TCustomDecisionGraph

Derived from TChart

CalcClickedPart

CalcMetaBounds

ChartPrintRect

CopyToClipboardBitmap

CopyToClipboardMetafile

DrawToMetaCanvas

ExchangeSeries

FillSeriesSourceItems

FillValueSourceItems

GetEditorClass

IsScreenHighColor

NextPage

PreviousPage

Print

PrintLandscape

PrintOrientation

PrintPartial

PrintPartialCanvas

PrintPortrait

PrintRect

SaveToBitmapFile

SaveToMetafile

SaveToMetafileEnh

SaveToMetafileRect

SeriesDown

SeriesUp

TeeCreateMetafile

UndoZoom

ZoomPercent

ZoomRect

Derived from TCustomChart

ActiveSeriesLegend

AddSeries

BackWallRect

CalcSize3d

CalcSize3dWalls

ChartRegionRect

CheckDatasource

CheckPenWidth

ClipRectangle

Draw

FormattedLegend

FormattedValueLegend

FreeAllSeries

GetASeries

GetAxisSeries

GetFreeSeriesColor

GetLabelsSeries

InternalDraw

IsFreeSeriesColor

IsValidDataSource

MarkText

MaxMarkWidth

MaxTextWidth

MaxXValue

MaxYValue

MinXValue

MinYValue

NumPages

RemoveAllSeries

RemoveSeries

SeriesCount

SeriesTitleLegend

UnClipRectangle

XLabelText

Derived from TCustomTeePanel

CanvasChanged

DoHorizLine

DoLine

DoPolygon

DoRectangle

DoVertLine

FontCanvas

GetCursorPos

GetRectangle

GetWidthHeight

ReCalcWidthHeight

RotateLabel

SetBooleanProperty

SetBrushCanvas

SetColorProperty

SetDoubleProperty

SetIntegerProperty

SetInternalCanvas

SetLongintProperty

SetStringProperty

TeeCharHeight

TeeTextHeight

TeeTextOut

TeeTextWidth

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomDecisionGraph methods

TCustomDecisionGraph	By object

~TCustomDecisionGraph

ActiveSeriesLegend

AddSeries

Assign

BackWallRect

BeginDrag

BringToFront

Broadcast

CalcClickedPart

CalcMetaBounds

CalcSize3d

CalcSize3dWalls

CanFocus

CanvasChanged

ChartPrintRect

ChartRegionRect

CheckDatasource

CheckPenWidth

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ClipRectangle

ContainsControl

ControlAtPos

CopyToClipboardBitmap

CopyToClipboardMetafile

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DoHorizLine

DoLine

DoPolygon

DoRectangle

DoVertLine

DragDrop

Dragging

Draw

DrawToMetaCanvas

EnableAlign

EndDrag

ExchangeSeries

FieldAddress

FillSeriesSourceItems

FillValueSourceItems

FindComponent

Focused

FontCanvas

FormattedLegend

FormattedValueLegend

Free

FreeAllSeries

FreeInstance

FreeNotification

FreeOnRelease

GetASeries

GetAxisSeries

GetCursorPos

GetEditorClass

GetFreeSeriesColor

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLabelsSeries

GetNamePath

GetParentComponent

GetRectangle

GetTabOrderList

GetTextBuf

GetTextLen

GetWidthHeight

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

InternalDraw

Invalidate

IsFreeSeriesColor

IsScreenHighColor

IsValidDataSource

MarkText

MaxMarkWidth

MaxTextWidth

MaxXValue

MaxYValue

MethodAddress

MethodName

MinXValue

MinYValue

NewInstance

NextPage

NumPages

PaintTo

Perform

PreviousPage

Print

PrintLandscape

PrintOrientation

PrintPartial

PrintPartialCanvas

PrintPortrait

PrintRect

Realign

ReCalcWidthHeight

Refresh

RemoveAllSeries

RemoveComponent

RemoveControl

RemoveSeries

Repaint

RotateLabel

SafeCallException

SaveToBitmapFile

SaveToMetafile

SaveToMetafileEnh

SaveToMetafileRect

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SeriesCount

SeriesDown

SeriesTitleLegend

SeriesUp

SetBooleanProperty

SetBounds

SetBrushCanvas

SetColorProperty

SetDoubleProperty

SetFocus

SetIntegerProperty

SetInternalCanvas

SetLongintProperty

SetStringProperty

SetTextBuf

Show

TCustomDecisionGraph

TeeCharHeight

TeeCreateMetafile

TeeTextHeight

TeeTextOut

TeeTextWidth

UnClipRectangle

UndoZoom

Update

UpdateControlState

XLabelText

ZoomPercent

ZoomRect


TCustomDecisionGraph::TCustomDecisionGraph

TCustomDecisionGraph	See also

Creates and initializes an instance of TCustomDecisionGraph.

__fastcall virtual TCustomDecisionGraph(Classes::TComponent* AOwner);

Description

Do not create instances of TCustomDecisionGraph. Instead, create a descendant of TCustomDecisionGraph such as TDecisionGraph. Decision graphs placed in forms at design time are created automatically.

Pass a single Component as a parameter to provide the decision graph with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the decision graph in a non-VCL window. This syntax is used when the graph is implemented as an ActiveX control that is embedded in a non-VCL window.


TCustomDecisionGraph::~TCustomDecisionGraph

TCustomDecisionGraph	See also

Destroys an instance of TCustomDecisionGraph.

__fastcall virtual ~TCustomDecisionGraph(void);

Description

Do not call ~TCustomDecisionGraph directly in an application. Instead, use the delete keyword.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomPanel

TCustomTeePanel

TCustomChart

TChart


TCustomDecisionGrid

Hierarchy	Properties	Methods	Events	See also

TCustomDecisonGrid is the base class for controls that present crosstabulated data in a two-dimensional grid.

Unit

mxgrid

Description

Use TCustomDecisionGrid as a base class when defining a decision grid object. Decision grids can present a single summary that is calculated over an arbitrary number of dimensions.

The field that is summarized and the fields (dimensions) over which it is summarized can be changed dynamically at runtime to view any configuration of summary and dimensions chosen from the dimension map of a decision cube. Changes to the dimensions and summary can be initiated by direct manipulation of the decision grid, or by using a TDecisionPivot object.

Do not create instances of TCustomDecisionGrid. To add a decision grid to a form, use the TDecisionGrid object.


TCustomDecisionGrid properties

TCustomDecisionGrid	Alphabetically	Legend

In TCustomDecisionGrid

CaptionColor

CaptionFont

Cells

ColCount

ColWidth

DataColor

DataFont

DataSumColor

DecisionSource

DefaultColWidth

DefaultRowHeight

Dimensions

FixedCols

FixedRows

GridLineColor

GridLineWidth

LabelColor

LabelFont

LabelSumColor

Options

RowCount

RowHeight

ShowCubeEditor

Totals

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomDecisionGrid properties

TCustomDecisionGrid	By object	Legend

Align

BoundsRect

Brush

CaptionColor

CaptionFont

Cells

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ColCount

ColWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DataColor

DataFont

DataSumColor

DecisionSource

DefaultColWidth

DefaultRowHeight

DesignInfo

Dimensions

Enabled

FixedCols

FixedRows

GridLineColor

GridLineWidth

Handle

Height

HelpContext

Hint

LabelColor

LabelFont

LabelSumColor

Left

Name

Options

Owner

Parent

ParentWindow

RowCount

RowHeight

ShowCubeEditor

ShowHint

Showing

TabOrder

TabStop

Tag

Top

Totals

VCLComObject

Visible

Width

WindowProc


TCustomDecisionGrid::CaptionColor

TCustomDecisionGrid	See also

Specifies the background color of cells containing the names of the row and column dimensions.

__property Graphics::TColor CaptionColor = {read=FCaptionColor, write=SetCaptionColor, nodefault};

Description

Set CaptionColor to the color that should be used to make the names of the row and column dimensions stand out. These are the names for the dimensions that are set in the Decision Cube Editor.

The actual values of the fields that make up the row and column dimensions are drawn using the LabelColor property.


TCustomDecisionGrid::CaptionFont

TCustomDecisionGrid	See also

Specifies the font used to write the names of the row and column dimensions.

__property Graphics::TFont* CaptionFont = {read=FCaptionFont, write=SetCaptionFont};

Description

Set CaptionFont to the font that should be used to make the names of the row and column dimensions stand out. These are the names for the dimensions that are set in the Decision Cube Editor.

The actual values of the fields that make up the row and column dimensions are written using the LabelFont property.


TCustomDecisionGrid::Cells

TCustomDecisionGrid	See also

Provides indexed access to the values of all cells in the decision grid.

__property System::AnsiString Cells[int ACol][int ARow] = {read=GetCells};

Description

Use Cells to obtain the value of a cell in the grid, formatted as a string. The ACol and ARow parameters indicate the column and row indexes of the cell, where (0,0) indicates the top left cell of the data region (not the top left cell of the grid). Cells that have been closed up using the Display Data or Display SubTotals menu items are still counted even though they are not visible.

If the cell is a row or column caption (negative value for ACol or ARow), Cells returns the name of the dimension. If the cell is a row or column label, Cells returns the field value of the dimension field. If the cell is a subtotal label, Cells returns the string Sum. If the cell is in the data region of the grid, Cells returns the summarized value.


TCustomDecisionGrid::ColCount

TCustomDecisionGrid	See also

Indicates the total number of columns in the decision grid.

__property int ColCount = {read=GetColCount, nodefault};

Description

Read ColCount to determine the number of columns in the decision grid, including the columns containing dimension captions and label cells. Compute the number of columns in the data region of the decision grid by subtracting the value of FixedCols from ColCount.


TCustomDecisionGrid::ColWidth

TCustomDecisionGrid	See also

Specifies the default column width.

__property int ColWidth = {read=FColWidth, write=SetColWidth, nodefault};

Description

Set ColWidth to the desired width of the columns in the decision grid that are not resized by the user. Setting ColWidth changes the size of all columns in the grid, including columns that have been resized using the mouse.


TCustomDecisionGrid::DataColor

TCustomDecisionGrid	See also

Specifies the background color of the cells containing summarized values.

__property Graphics::TColor DataColor = {read=FDataColor, write=SetDataColor, nodefault};

Description

Set DataColor to the color that should be used for the scrollable data region of the decision grid. The data region contains the values of the current summary of the decision cube, where each cell represents the value of a field summarized over the values indicated by the row and column dimensions.

The subtotals that represent values summarized over all values within a given dimension (as well as the single value in other dimensions) are drawn using the DataSumColor property.


TCustomDecisionGrid::DataFont

TCustomDecisionGrid	See also

Specifies the font used to write the summarized values in the scrollable region of the decision grid.

__property Graphics::TFont* DataFont = {read=FDataFont, write=SetDataFont};

Description

Set DataFont to the font that should be used for the data region of the decision grid. The data region contains the values of the current summary of the decision cube, where each cell represents the value of a field summarized over the values indicated by the row and column dimensions. It also includes the dimension subtotals over the summary field.


TCustomDecisionGrid::DataSumColor

TCustomDecisionGrid	See also

Specifies the background color of cells that represent subtotals over entire dimensions.

__property Graphics::TColor DataSumColor = {read=FDataSumColor, write=SetDataSumColor, nodefault};

Description

Set DataSumColor to make the subtotals that represent an entire dimension stand out from the summary values that summarize information over a single value in each dimension. The subtotal cells are placed in the scrollable data region at the ends of the set of rows or columns that correspond to a given dimension.


TCustomDecisionGrid::DecisionSource

TCustomDecisionGrid	See also

Specifies the decision source that supplies crosstabulated data to the decision grid.

__property Mxdb::TDecisionSource* DecisionSource = {read=GeTDecisionSource, write=SeTDecisionSource};

Description

Set DecisionSource to link the decision grid to the crosstabulated data from a decision cube. The DecisionSource object maintains information about the current pivot state of the data. Thus, any two decision controls that share the same decision source will display the data from the decision cube using the same configuration of row and column dimensions, including any closed dimensions or drilled down values.


TCustomDecisionGrid::DefaultColWidth

TCustomDecisionGrid	See also

Specifies the width of all columns that are not explicitly resized.

__property int DefaultColWidth = {read=FColWidth, write=SetColWidth, nodefault};

Description

Set DefaultColWidth to the desired width of the columns in the decision grid that are not resized using the mouse. Setting DefaultColWidth changes the size of all columns in the grid, including columns that have been resized.


TCustomDecisionGrid::DefaultRowHeight

TCustomDecisionGrid	See also

Specifies the height of all rows that are not explicitly resized.

__property int DefaultRowHeight = {read=FRowHeight, write=SetRowHeight, nodefault};

Description

Set DefaultRowHeight to the desired height of the rows in the decision grid that are not resized using the mouse. Setting DefaultRowHeight changes the size of all rows in the grid, including rows that have been resized.


TCustomDecisionGrid::Dimensions

TCustomDecisionGrid	See also

Provides access to the collection of TDisplayDim objects that control the appearance of each dimension.

__property TDisplayDims* Dimensions = {read=FDisplayDims, write=FDisplayDims};

Description

Set the properties of the individual TDisplayDim objects to control the appearance of individual dimensions within the grid. The TDisplayDim objects have properties that can override the various color and font properties of the grid to make individual dimensions stand out. They also allow the dimension names, alignments, and formats to be customized, and permit the dimension subtotals for a dimension to be turned on or off.

Note:	Do not change the Dimensions property, only the properties of individual TDisplayDim objects accessed through the Dimensions property. To programmatically change the configuration of dimensions that appears in the grid, use the decision source object.


TCustomDecisionGrid::FixedCols

TCustomDecisionGrid	See also

Indicates the number of columns used for dimension captions and dimension value labels.

__property int FixedCols = {read=GetFixedCols, nodefault};

Description

Read FixedCols to determine the number of columns in the decision grid that are not part of the data region. Subtract FixedCols from the value of the ColCount property to obtain the number of columns in the data region.


TCustomDecisionGrid::FixedRows

TCustomDecisionGrid	See also

Indicates the number of rows used for dimension captions and dimension value labels.

__property int FixedRows = {read=GetFixedRows, nodefault};

Description

Read FixedRows to determine the number of rows in the decision grid that are not part of the data region. Subtract FixedRows from the value of the RowCount property to obtain the number of rows in the data region.


TCustomDecisionGrid::GridLineColor

TCustomDecisionGrid	See also

Specifies the color of the lines that separate the cells in the decision grid.

__property Graphics::TColor GridLineColor = {read=FGridLineColor, write=SetGridLineColor, nodefault};

Description

Set GridLineColor to specify the color of the lines drawn between the cells of the grid. The grid lines only appear when the Options property includes cgGridLines.


TCustomDecisionGrid::GridLineWidth

TCustomDecisionGrid	See also

Specifies the width, in pixels, of the lines that separate the cells of the grid.

__property int GridLineWidth = {read=FGridLineWidth, write=SetGridLineWidth, nodefault};

Description

Set GridLineWidth to make the lines that separate the cells in the decision grid heavier or lighter. The grid lines only appear when the Options property includes cgGridLines.


TCustomDecisionGrid::LabelColor

TCustomDecisionGrid	See also

Specifies the color of the individual row and column labels.

__property Graphics::TColor LabelColor = {read=FLabelColor, write=SetLabelColor, nodefault};

Description

Set LabelColor to the color that should be used to make the row and column labels stand out. The row and column labels of the decision grid contain the values of the fields that correspond to the dimensions of the decision cube. These are the values over which the data is summarized.


TCustomDecisionGrid::LabelFont

TCustomDecisionGrid	See also

Specifies the font used to write the individual row and column labels.

__property Graphics::TFont* LabelFont = {read=FLabelFont, write=SetLabelFont};

Description

Set LabelFont to the font that should be used to write the labels that display the values of the dimensions over which data is summarized. The row and column labels of the decision grid contain the values of the fields that correspond to the dimensions of the decision cube. LabelFont is also used when writing the labels for rows or columns that represent dimension subtotals.


TCustomDecisionGrid::LabelSumColor

TCustomDecisionGrid	See also

Specifies the background color for the subtotal labels.

__property Graphics::TColor LabelSumColor = {read=FLabelSumColor, write=SetLabelSumColor, nodefault};

Description

Set LabelSumColor make the subtotal labels stand out from the labels that represent individual field values along a dimension. The subtotal labels appear at the end of the set of field value labels for an individual dimension.


TCustomDecisionGrid::Options

TCustomDecisionGrid	See also

Specifies settings that affect the entire grid display.

enum TDecisionGridOption { cgGridLines, cgOutliner, cgPivotable };

typedef Set<TDecisionGridOption, cgGridLines, cgPivotable> TDecisionGridOptions;

__property TDecisionGridOptions Options = {read=FOptions, write=SetOptions, default=7};

Description

Set Options to include the desired properties for the grid. Options is a set drawn from the following values:

Value	Meaning

cgGridLines	Vertical and horizontal lines are drawn to separate the cells in the scrollable data region.

cgOutliner	The dimension caption cells contain plus (+) and minus (-) signs that open or close dimensions in the grid when clicked. The minus sign closes (hides) an adjacent dimension. The plus sign opens (shows) an adjacent dimension.

cgPivotable	Dimensions can be rearranged by clicking on the dimension caption cells and dragging them to a new position.

Note:	If Options does not include cgOutliner, individual dimensions can still be opened and closed using the decision pivot. Similarly, if Options does not include cgPivotable, individual dimensions can still be opened and closed with the decision pivot.


TCustomDecisionGrid::RowCount

TCustomDecisionGrid	See also

Indicates the total number of rows in the decision grid.

__property int RowCount = {read=GetRowCount, nodefault};

Description

Read RowCount to determine the number of rows in the decision grid, including the rows containing dimension captions and label cells. Compute the number of rows in the data region of the decision grid by subtracting the value of FixedRows from RowCount.


TCustomDecisionGrid::RowHeight

TCustomDecisionGrid	See also

Specifies the default row height.

__property int RowHeight = {read=FRowHeight, write=SetRowHeight, nodefault};

Description

Set RowHeight to the desired height of the rows in the decision grid that are not resized by the user. Setting RowHeight changes the size of all rows in the grid, including rows that have been resized using the mouse.


TCustomDecisionGrid::ShowCubeEditor

TCustomDecisionGrid	See also

Determines whether the Cube Editor can be displayed.

__property bool ShowCubeEditor = {read=FShowCubeEditor, write=FShowCubeEditor, nodefault};

Description

Determines whether the Cube Editor for the associated TDecisionCube can be invoked. If set to true, a menu item to invoke the Cube Editor is added to the speed menu displayed on a right-click on the decision grid at runtime.


TCustomDecisionGrid::Totals

TCustomDecisionGrid	See also

Indicates whether the grid includes subtotals.

__property bool Totals = {read=GetTotals, write=SetTotals, nodefault};

Description

Set Totals to turn row and column subtotals on or off for the whole grid. To turn subtotals on or off for individual dimensions, use the Dimensions property.


TCustomDecisionGrid events

TCustomDecisionGrid	Alphabetically

In TCustomDecisionGrid

OnDecisionDrawCell

OnDecisionExamineCell

OnTopLeftChanged


TCustomDecisionGrid events

TCustomDecisionGrid	By object

OnDecisionDrawCell

OnDecisionExamineCell

OnTopLeftChanged


TCustomDecisionGrid::OnDecisionDrawCell

TCustomDecisionGrid	See also

Occurs just before a cell in the grid is drawn.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed>  TGridDrawState;

enum TDecisionDrawStates { dsGroupStart, dsRowCaption, dsColCaption, dsSum, dsRowValue, dsColValue, dsData, dsOpenAfter, dsCloseAfter, dsCloseBefore, dsOpenBefore, dsRowIndicator, dsColIndicator, dsRowPlus, dsColPlus, dsNone };

typedef Set<TDecisionDrawStates, dsGroupStart, dsNone> TDecisionDrawState;

typedef void __fastcall (__closure *TDecisionDrawCellEvent)(System::TObject* Sender, int Col, int Row, System::AnsiString &Value, Graphics::TFont* &aFont, Graphics::TColor &aColor, Grids::TGridDrawState AState, TDecisionDrawState aDrawState);

__property TDecisionDrawCellEvent OnDecisionDrawCell = {read=FOnDecisionDrawCell, write=FOnDecisionDrawCell};

Description

Write an OnDecisionDrawCell event handler to change the color, font, or text used to display an individual cell in the grid. Change the AColor, AFont, or Value parameter to change the color, font, or text respectively.

For example, to change the row and column labels from the values of the fields in the dataset to customized labels, change the Value parameter of the event handler when the Row and Column parameters represent a label cell.

The Row and Column parameters indicate the row and column of a cell within the grid, where (0,0) specifies the upper left summary value, not the upper left corner of the grid. Thus, the label cells contain negative row or column indexes. In addition, the AState parameter includes gdFixed when the cell is a label cell. AState also indicates whether the cell being drawn is selected.

The ADrawState parameter indicates the type of cell that is about to be drawn. ADrawState includes one or more of the following values:

Value	Meaning

dsGroupStart	The cell is the first row or column label for a dimension. Always appears with dsRowValue or dsColValue.

dsRowCaption	The cell displays a row caption (the name of a dimension whose values are listed down a column on the left of the grid).

dsColCaption	The cell displays a column caption (the name of a dimension whose values are listed along the top of the grid).

dsSum	The cell displays a subtotal label or value. Always appears with dsRowValue, dsColValue, or dsData.

dsRowValue	The cell is a row label. It represents a value from a dimension listed down a column on the left of the grid or a summary label that appears at the end of each group of dimension values.

dsColValue	The cell is a column label. It represents a value from a dimension listed across the top of the grid or a summary label that appears at the end of the dimension.

dsData	The cell is in the scrollable data region of the grid.

dsOpenAfter	The cell has a plus sign (+) on the right that will open following dimension when clicked. Always appears with dsRowCaption, dsColCaption, dsRowPlus, or dsColPlus.

dsCloseAfter	The cell has a minus sign (-) on the right that will close the following dimension when clicked. Always appears with dsRowCaption, dsColCaption, dsRowPlus, or dsColPlus.

dsRowIndicator	The cell appears on the left grid margin that is used to display the open and close indicators (+ and -).

dsColIndicator	The cell appears on the upper grid margin that is used to display the open and close indicators (+ and -).

dsRowPlus	The cell appears in the left margin and contains a plus sign (+) indicating that the adjacent dimension is closed. Always appears with dsRowIndicator.

dsColPlus	The cell appears in the top margin and contains a plus sign (+) indicating that the adjacent dimension is closed. Always appears with dsColIndicator.

dsNone	The cell has no function.


TCustomDecisionGrid::OnDecisionExamineCell

TCustomDecisionGrid	See also

Occurs when the user right-clicks on a cell in the data region of the grid.

typedef void __fastcall (__closure *TDecisionExamineCellEvent)(System::TObject* Sender, int iCol, int iRow, int iSum, const TSmallIntArray* ValueArray);

__property TDecisionExamineCellEvent OnDecisionExamineCell = {read=FOnDecisionExamineCell, write=FOnDecisionExamineCell};

Description

Write an OnDecisionExamineCell event handler to take specific action when the user right-clicks on one of the cells that contains summarized data. The ICol and IRow parameters indicate the column and row indexes of the cell. The column and row indexes specify the value 0 for the top or leftmost cell in the scrollable data region, not the top left cell of the decision grid. The ISum parameter is the index of the current summary in the decision cube, where the first active summary has an index of 0. The ValueArray parameter gives the coordinates of the cell in terms of the dimensions of the decision source. If the cell represents a subtotal value, the entry in the ValueArray for the dimension over which the subtotal is calculated is a negative number.

Use the Cells property to obtain the value of the summary in the cell. Use the GetDimensionName method of the decision source to get the name of each dimension represented by an entry in the ValueArray parameter. Use the GetValueAsString or GetValueAsVariant method of the decision source to obtain the label values for each dimension represented in the ValueArray parameter.


TCustomDecisionGrid::OnTopLeftChanged
 KTCustomDecisionGrid::OnTopLeftChanged

TCustomDecisionGrid	See also

Occurs when the data region of the grid scrolls.

__property Classes::TNotifyEvent OnTopLeftChanged = {read=FOnTopLeftChanged, write=FOnTopLeftChanged};

Description

Write an OnTopLeftChanged event handler to take specific action when the summarized data in the grid scrolls. Use the Cells property or the CellDrawState method to obtain the new values of the data cells.


TCustomDecisionGrid methods

TCustomDecisionGrid	Alphabetically	Legend

In TCustomDecisionGrid

~TCustomDecisionGrid

CellDrawState

CellValueArray

ColWidthsChanged

DrawCell

GetCells

MouseDown

MouseMove

MouseUp

Notification

Paint

RowHeightsChanged

SelectCell

TCustomDecisionGrid

TopLeftChanged

Derived from TCustomGrid

MouseCoord

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomDecisionGrid methods

TCustomDecisionGrid	By object	Legend

~TCustomDecisionGrid

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CellDrawState

CellValueArray

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ColWidthsChanged

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

DrawCell

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetCells

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

MouseCoord

MouseDown

MouseMove

MouseUp

NewInstance

Notification

Paint

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

RowHeightsChanged

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectCell

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomDecisionGrid

TopLeftChanged

Update

UpdateControlState


TCustomDecisionGrid::CellDrawState

TCustomDecisionGrid	See also

Retrieves information about a data cell in the grid.

enum TDecisionDrawStates { dsGroupStart, dsRowCaption, dsColCaption, dsSum, dsRowValue, dsColValue, dsData, dsOpenAfter, dsCloseAfter, dsCloseBefore, dsOpenBefore, dsRowIndicator, dsColIndicator, dsRowPlus, dsColPlus, dsNone };

typedef Set<TDecisionDrawStates, dsGroupStart, dsNone> TDecisionDrawState;

bool __fastcall CellDrawState(int ACol, int ARow, System::AnsiString &Value, TDecisionDrawState &DrawState);

Description

Call CellDrawState to obtain information about a cell in the scrollable data region of the grid. The ACol and ARow parameters specify the index of the cell, where (0,0) is the upper left cell in the data region, not the upper left cell in the grid. The Value parameter returns the value of the summary in the cell, formatted for display. The DrawState parameter returns information about the type of information contained in the cell. For more information about the possible values of DrawState, see the entry for the OnDecisionDrawCell event.

CellDrawState returns true if the Value and DrawState parameters are correctly filled in. CellDrawState returns false if the cell specified by ACol and ARow is not in the data region of the grid.


TCustomDecisionGrid::CellValueArray

TCustomDecisionGrid	See also

Returns the values of all dimension fields over which a data cell is summarized.

bool __fastcall CellValueArray(int ACol, int ARow, TSmallIntArray* &ValueArray);

Description

Call CellValueArray to obtain the coordinates of a data cell in the multidimensional array maintained by the decision cube. The ACol and ARow parameters represent the indexes of the column and row containing the cell, where (0,0) specifies the upper left data cell, not the top left cell in the grid. The ValueArray parameter returns the indexes of the field values for each dimension over which the cell summarizes data. Use the GetMemberAsString or GetMemberAsVariant method of the decision source to convert the indexes in the ValueArray parameter into field values. CellValueArray returns a boolean indicating whether the function was successful.


TCustomDecisionGrid::ColWidthsChanged

TCustomDecisionGrid	See also

Responds when the column widths change.

DYNAMIC void __fastcall ColWidthsChanged(void);

Description

ColWidthsChanged is called immediately after the column widths change. The change can result from setting the ColWidth property or from resizing the columns with the mouse.

ColWidthsChanged adjusts the scroll bar to accommodate the change. At design time, ColWidthsChanged forces all columns to have the same size when the columns are resized using the mouse.


TCustomDecisionGrid::TCustomDecisionGrid

TCustomDecisionGrid	See also

Creates and initializes an instance of TCustomDecisionGrid.

__fastcall virtual TCustomDecisionGrid(Classes::TComponent* AOwner);

Description

Do not create instances of TCustomDecisionGrid. Instead, create a descendant of TCustomDecisionGrid such as TDecisionGrid.

TCustomDecisionGrid initializes the following properties:

•	CaptionColor to clActiveCaption and CaptionFont::Color to clCaptionText.

•	DataColor to clInfoBk and DataSumColor to clNone.

•	LabelColor to clBtnFace and LabelSumColor to clTeal.

•	Color to clWindow and ParentColor to false.

•	Options to [cgGridLines, cgOutliner, cgPivotable].

•	GridLineColor to clBlack and GridLineWidth to 1.

•	ColWidth to 80 and RowHeight to 20.

•	ScrollBars to ssBoth.

•	DefaultDrawing to true.


TCustomDecisionGrid::~TCustomDecisionGrid

TCustomDecisionGrid	See also

Destroys an instance of TCustomDecisionGrid.

__fastcall virtual ~TCustomDecisionGrid(void);

Description

Do not call ~TCustomDecisionGrid directly in an application. Instead, use the delete keyword. ~TCustomDecisionGrid frees all helper objects used by TCustomDecisionGrid.


TCustomDecisionGrid::DrawCell

TCustomDecisionGrid	See also

Draws a cell in the grid.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

virtual void __fastcall DrawCell(int ACol, int ARow, const Windows::TRect &ARect, Grids::TGridDrawState AState);

Description

DrawCell is called automatically when the cell specified by the ACol and ARow parameters needs to be painted. DrawCell generates an OnDecisionDrawCell event, and then draws the cell using the color, font, and value for the cell.


TCustomDecisionGrid::GetCells

TCustomDecisionGrid	See also

Returns the value of a cell in the grid, formatted as a string.

System::AnsiString __fastcall GetCells(int ACol, int ARow);

Description

GetCells is the protected property access method for the Cells property. Override GetCells to change the implementation of the Cells property.


TCustomDecisionGrid::MouseDown

TCustomDecisionGrid	See also

Starts the drag of a dimension to a new location.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseDown(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

MouseDown is called automatically when the user clicks the mouse in a cell of the grid. After calling the parent class’s method, MouseDown starts a pivot operation if the cell is a dimension label that can be dragged.

When overriding the MouseDown method, be sure to call the parent class’s method.


TCustomDecisionGrid::MouseMove

TCustomDecisionGrid	See also

Computes the drop site of a pivoting dimension.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseMove(Classes::TShiftState Shift, int X, int Y);

Description

MouseMove is called automatically when the user moves the mouse. After calling the parent class’s method, MouseMove calculates the new pivot state if a dimension is being dragged to a new location.

When overriding the MouseMove method, be sure to call the parent class’s method.


TCustomDecisionGrid::MouseUp

TCustomDecisionGrid	See also

Rearranges the dimensions after a pivot and updates the decision source.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseUp(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

MouseUp is called automatically when the user releases the mouse. After calling the parent class’s method, MouseUp checks whether a dimension was just dragged to a new location. If a dimension was just moved, MouseUp changes the Dimensions property appropriately and updates the decision source to reflect the new configuration.

When overriding the MouseUp method, be sure to call the parent class’s method.


TCustomDecisionGrid::Notification

TCustomDecisionGrid	See also

Links the buttons in TDecisionPivot to the decision source.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the parent class’s method, Notification performs the necessary internal adjustments when new elements are added to the decision grid. When overriding the Notification method, be sure to call the parent class’s method.


TCustomDecisionGrid::Paint

TCustomDecisionGrid	See also

Renders the image of the decision grid.

virtual void __fastcall Paint(void);

Description

Paint is called when the grid receives a Windows paint message. Paint draws the grid, calling the DrawCell method when it is time to paint the contents of each cell. After all the cells are drawn, Paint draws the grid lines.

If DefaultDrawing is false, Paint does not draw the background of the cells or draw the focus rectangle around the selected cell when it has focus.


TCustomDecisionGrid::RowHeightsChanged

TCustomDecisionGrid	See also

Responds when the row heights change.

DYNAMIC void __fastcall RowHeightsChanged(void);

Description

RowHeightsChanged is called immediately after the row heights change. The change can result from setting the RowHeight property or from resizing the rows with the mouse.

RowHeightsChanged adjusts the scroll bar to accommodate the change. At design time, RowHeightsChanged forces all rows to have the same size when the rows are resized using the mouse.


TCustomDecisionGrid::SelectCell

TCustomDecisionGrid	See also

Determines whether a specified cell can be selected.

virtual bool __fastcall SelectCell(int Arow, int AColumn);

Description

Decision grids call SelectCell internally before attempting to move selection to the cell identified by the ACol and ARow parameters. ACol and ARow are the column and row indexes for the cell, where the first column has index 0, and the top row has index 0.


TCustomDecisionGrid::TopLeftChanged

TCustomDecisionGrid	See also

Generates an OnTopLeftChanged event.

DYNAMIC void __fastcall TopLeftChanged(void);

Description

Decision grids call TopLeftChanged internally, whenever the data region of the grid scrolls.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGrid


TCGIApplication

Hierarchy	Properties	Methods	See also

TCGIApplication encapsulates a CGI server application.

Unit

cgiapp

Description

TCGIApplication provides the fundamental behavior of a CGI server application. TCGIApplication starts running when the CGI server receives an HTTP request message. It creates TCGIRequest and TCGIResponse objects to represent the request message and any response that should be sent in return, passes these to the dispatcher so that the response can be filled in, and sends the response if it was not already sent by a TWebActionItem.

Each CGI server project automatically declares an Application variable of type TCGIApplication as the instance of the application. This declaration overrides the Application variable declared in the Forms unit if the CGIApp unit is declared last in the uses list of the project file. Every CGI server application must include the CGIApp unit.

To work with an ISAPI or NSAPI server, use the TISAPIApplication object instead.


TCGIApplication properties

TCGIApplication	Alphabetically	Legend

Derived from TWebApplication

ActiveCount

CacheConnections

InactiveCount

MaxConnections

Title

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCGIApplication properties

TCGIApplication	By object	Legend

ActiveCount

CacheConnections

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

InactiveCount

MaxConnections

Name

Owner

Tag

Title

VCLComObject


TCGIApplication methods

TCGIApplication	Alphabetically

In TCGIApplication

~TCGIApplication

Run

TCGIApplication

Derived from TWebApplication

CreateForm

Initialize

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCGIApplication methods

TCGIApplication	By object

~TCGIApplication

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateForm

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

Initialize

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

Run

SafeCallException

TCGIApplication


TCGIApplication.Run

TCGIApplication	See also

Executes the CGI application in response to an HTTP request message.

virtual void __fastcall Run(void);

Description

When creating a new project, C++Builder automatically creates a main program block in the project file that calls the Run method. When the application is started in response to an HTTP request message, the CGI application’s Run method is called.

After calling TWebApplication::Run to set up the default error handler and shut down sequence for the application, TCGIApplication::Run creates the appropriate request and response objects for the HTTP request message that started the CGI application. Run calls the HandleRequest method to pass the request and response on to the dispatcher where the response is filled out and sent. Finally, Run frees the request and response objects.


TCGIApplication::TCGIApplication

TCGIApplication

Creates a new TCGIApplication object.

__fastcall virtual TCGIApplication(Classes::TComponent* AOwner) : Httpapp::TWebApplication(AOwner) { }

Description

Do not call the constructor of TCGIApplication. Instead, use the global Application variable that is instantiated from the project file.


TCGIApplication::~TCGIApplication

TCGIApplication

Frees the memory associated with the TCGIApplication object.

__fastcall virtual ~TCGIApplication(void) { }

Description

Do not call ~TCGIApplication. The global Application variable is freed when the application shuts down.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TWebApplication


TCGIRequest

Hierarchy	Properties	Methods	See also

TCGIRequest represents client request information that is passed to a CGI Web server application.

Unit

cgiapp

Description

Use TCGIRequest to interpret an HTTP request to a CGI server application.

CGI application objects create TCGIRequest objects to capture client requests. The properties of TCGIRequest are obtained from the Web server. The CGI application uses TCGIRequest objects to create corresponding TCGIResponse objects. The TWebDispatcher for the application then invokes the TWebActionItem that is associated with the path portion of the URL of the TCGIRequest object.


TCGIRequest properties

TCGIRequest	Alphabetically	Legend

In TCGIRequest

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentLength

ContentType

ContentVersion

Cookie

Date

DerivedFrom

Expires

From

Host

IfModifiedSince

Method

PathInfo

PathTranslated

ProtocolVersion

Query

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent

Derived from TWebRequest

ContentFields

CookieFields

MethodType

QueryFields


TCGIRequest properties

TCGIRequest	By object	Legend

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentFields

ContentLength

ContentType

ContentVersion

Cookie

CookieFields

Date

DerivedFrom

Expires

From

Host

IfModifiedSince

Method

MethodType

PathInfo

PathTranslated

ProtocolVersion

Query

QueryFields

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent


TCGIRequest::Accept

TCGIRequest	See also

Represents the value of the Accept header of the HTTP request message.

__property System::AnsiString Accept = {read=GetStringVariable, index=8};

Description

Read Accept to determine the media types the Web client can accept in response to the request. Not every HTTP request message has an Accept header. If the Accept property is not set, then any media type is potentially acceptable in the response.

Accept headers usually indicate that the response should be limited to a small set of desired types. For example, a Web client requesting an audio response might produce a TCGIRequest object with Accept set to the following string:

audio/*; q=0.2, audio/basic

This request indicates that the preferred response media type is audio/basic, but that any audio type is acceptable if it is the best available after an 80% mark-down in quality.

For information on the format of Accept headers, see the current Internet standards documentation.


TCGIRequest::Authorization

TCGIRequest	See also

Represents the value of the Authorization header of the HTTP request message.

__property System::AnsiString Authorization = {read=GetStringVariable, index=28};

Description

Read Authorization to check whether the client that sent the request message has provided the correct authentication information. Authorization allows the CGI application to provided limited access to the resource specified by the URL property.

For more information about HTTP authentication schemes, see the Internet standards documentation.


TCGIRequest::CacheControl

TCGIRequest 	See also

Represents the value of the Cache-Control header of the HTTP request message.

__property System::AnsiString CacheControl = {read=GetStringVariable, index=6};

Description

Read CacheControl to determine any Web client directives that must be obeyed by all caching mechanisms along the request/response chain. The CacheControl directives of the HTTP request do not need to apply to the corresponding response.

The HTTP 1.1 standard defines the following directives for CacheControl:

Value	Meaning
no-cache.	The request may not be cached. The Web server validates the request before the TCGIRequest object is created
max-age=ss	The request is considered invalid if it is older than ss seconds. This directive takes precedence over the Expires property, even if Expires is more restrictive. Invalid requests are validated by the Web server before the TCGIRequest object is created.
max-stale or max-stale=ss	The client is willing to accept a response that has exceeded its expiration time. The max-stale directive can optionally specify the number of seconds by which the response can exceed it’s expiration time.
min-fresh=ss	The client is not willing to accept a response that expires in less than ss seconds.
no-store	The request contains sensitive information and may not be stored on any permanent medium such as a back-up tape. If the request is stored temporarily in a file, the file must be deleted.


TCGIRequest::Connection

TCGIRequest	See also

Represents the value of the Connection header of the HTTP request message.

__property System::AnsiString Connection = {read=GetStringVariable, index=26};

Description

Read Connection to determine the options requested by the Web client for its connection to the server application. The HTTP 1.1 standard specifies only one value for the Connection header. If the value of Connection is close, then the connection should be closed after the completion of the response.


TCGIRequest::Content

TCGIRequest	See also

Represents the unparsed contents of the HTTP request message.

__property System::AnsiString Content = {read=GetStringVariable, index=25};

Description

Use Content to read the contents of an HTTP request message that is sending information to the server. The value of Content depends on the Method of the HTTP request. When the Method is POST, Content is the unparsed string giving the values to be posted with their associated fields. When the Method is PUT, Content is the value that should replace the URL given by the URL property.

Note:	When the Method is POST, the parsed version of the post request is available in the ContentFields property.


TCGIRequest::ContentEncoding

TCGIRequest	See also

Represents the value of the Content-Encoding header of the HTTP request message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, index=14};

Description

Read ContentEncoding to determine what encoding mechanisms, if any, have been applied to the Content of the HTTP request. The encoding mechanisms are listed in the order in which they were applied by the Web client, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding scheme used to transfer extended ASCII characters over the net.

Reverse the ContentEncoding mechanisms to decode the Content into the form indicated by the ContentType property.


TCGIRequest::ContentLength

TCGIRequest	See also

Represents the value of the Content-Length header of the HTTP request message.

__property int ContentLength = {read=GetIntegerVariable, index=16, nodefault};

Description

Read the ContentLength property to determine the length of the Content property. ContentLength allows an application to determine the end of the Content property when the ContentType is not text/html. A ContentLength of 0 indicates that the length of the Content property is not determined, either because the request does not include any Content, or because the Web client did not know the length.

Note:	The length of the Content may be less than ContentLength when the Content is passed by chunked transfer coding.


TCGIRequest::ContentType

TCGIRequest	See also

Represents the value of the Content-Type header of the HTTP request message.

__property System::AnsiString ContentType = {read=GetStringVariable, index=15};

Description

Read ContentType to determine the media type of the Content of the HTTP request message. The ContentType is a string of the form Type/SubType.

Most HTTP requests do not require any Content at all. For most requests with a Method that requires a value for Content, the ContentType is text/html. However, HTTP requests for server-specific values of Method can use any media type appropriate to the request.


TCGIRequest::ContentVersion

TCGIRequest	See also

ContentVersion is the value of the Content-Version header of the HTTP request message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, index=17};

Description

Read ContentVersion to determine the version of the Content of the HTTP request message. Most HTTP requests do not require any Content at all. When the Method requires a value for Content, the ContentVersion may be set to indicate the version of the source of that content. The format of the ContentVersion depends on the ContentType of the request.


TCGIRequest::Cookie

TCGIRequest	See also

Represents the value of the Cookie header of the HTTP request message.

__property System::AnsiString Cookie = {read=GetStringVariable, index=27};

Description

Use Cookie to read the “cookie” strings provided in the Web client request. Cookie strings are generally used to track state information in a Web application. Usually the value is passed on from a cookie header sent in a previous response message.

Cookie is the unparsed value of the Cookie header. The Cookie header can include multiple fields separated by semicolons. Use the CookieFields property to work with the Cookie header on a field-by-field basis.


TCGIRequest::Date

TCGIRequest 	See also

Represents the value of the Date header of the HTTP request message.

__property System::TDateTime Date = {read=GetDateVariable, index=7};

Description

Read Date to determine the date and time at which the HTTP request message originated. Date can be used to determine whether the Content of the request is still valid. The value of Date is translated into local time as specified in the Windows Control Panel from the time units set by the Web client.

For example, if an HTTP request message specifies a MethodType of mtPost, and Date is older than the most recent values of the fields that are being posted, the server application may return a status code that indicates an error rather than overwriting more recent values.

Date is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TCGIRequest::DerivedFrom

TCGIRequest	See also

Represents the value of the Derived-From header of the HTTP request message.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, index=18};

Description

Read DerivedFrom to determine the URI where the value of Content originated. DerivedFrom is only meaningful when the request includes a Content property and the Content did not originate with the Web client.


TCGIRequest::Expires

TCGIRequest 	See also

Represents the value of the Expires header of the HTTP request message.

__property System::TDateTime Expires = {read=GetDateVariable, index=19};

Description

Use Expires to determine whether the request is “stale”. Expires is the date and time at which the request becomes invalid. The value of Expires is translated into local time as specified in the Windows Control Panel from the time units set by the Web client.

If the request has a CacheControl value with a max-age directive, the max-age directive overrides the value of Expires.

Expires is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TCGIRequest::From

TCGIRequest	See also

Represents the value of the From header of the HTTP request message.

__property System::AnsiString From = {read=GetStringVariable, index=9};

Description

Read From to determine the Internet e-mail address of the human user for whom the Web client sent the HTTP request message. This value can be used for logging purposes, or to contact the originator of the request if problems occur.


TCGIRequest::Host

TCGIRequest	See also

Represents the value of the Host header of the HTTP request message.

__property System::AnsiString Host = {read=GetStringVariable, index=10};

Description

Read Host to determine the Internet host and port number of resource being requested. For example, if the client request specifies the following URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

The value of Host would be

www.TSite.com

The value of Host can be used to differentiate between internally ambiguous URLs, such as the root “/” URL of a server for multiple host names on a single IP address.


TCGIRequest::IfModifiedSince

TCGIRequest 	See also

Represents the value of the If-Modified-Since header of the HTTP request message.

__property System::TDateTime IfModifiedSince = {read=GetDateVariable, index=11};

Description

Read IfModifiedSince on a request with a MethodType of mtGet to determine whether the request is conditional. If the information requested by the Web client was not modified since the time indicated by IfModifiedSince, the response should be a not modified error rather than the information indicated by the URL property.

The value of IfModifiedSince is given according to the local clock as specified in the Windows Control Panel, not the clock of the Web client.

IfModifiedSince is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TCGIRequest::Method

TCGIRequest	See also

Represents the value of the Method header of the HTTP request message.

__property System::AnsiString Method = {read=GetStringVariable, index=0};

Description

Read Method to determine the method that is requested by the Web client. The HTTP 1.1 standard defines the following methods:

Value	Meaning

OPTIONS	A request for information about available communication options.

GET	A request for the information identified by the URL property.

HEAD	A request for information about the properties of the HTTP response, but not for the content of the response.

POST	A request for the server application to post the data included in the Content property, as appropriate.

PUT	A request for the server application to replace the resource indicated by the URL property with the data included in the Content property.

DELETE	A request for the server application to delete or hide the resource identified by the URL property.

TRACE	A request for the server application to send a loop-back to confirm receipt of the request.

The Method property may indicate any other method that the Web client requests of the server. If the Method can’t be matched to the Allow property of a TCGIResponse object, the request can’t be serviced.

The MethodType property indicates whether the value of Method is GET, HEAD, POST, PUT, or one of the other strings. When possible, use MethodType instead of the Method property to save the overhead of string comparison.

Note:	A Web server application need not service all method types. However, there must be a response for the GET and HEAD method requests.


TCGIRequest::PathInfo

TCGIRequest	See also

Indicates the value of the path information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString PathInfo = {read=GetStringVariable, index=4};

Description

Read PathInfo to determine the path on the server machine where the target of the request is found. For example, given this URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the PathInfo portion is:

/mammals

The TWebDispatcher object uses the PathInfo to identify the appropriate TWebActionItem for servicing the request message.


TCGIRequest::PathTranslated

TCGIRequest	See also

Represents a translation of the PathInfo property to a fully qualified path on the Web server.

__property System::AnsiString PathTranslated = {read=GetStringVariable, index=5};

Description

Use PathTranslated to refer to the location of the target of the request in an HTTP response.


TCGIRequest::ProtocolVersion

TCGIRequest	See also

Indicates the version number of the HTTP protocol specified in the initial header of the HTTP request message.

__property System::AnsiString ProtocolVersion = {read=GetStringVariable, index=1};

Description

Use ProtocolVersion to determine the protocol used by the Web client when generating the HTTP request message.

Some properties of the HTTP request may be interpreted differently depending on the ProtocolVersion. For example, if ProtocolVersion is 1.0, then the connection should not be considered persistent, even if the Connection property does not specify the close option.


TCGIRequest::Query

TCGIRequest	See also

Indicates the value of the query information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString Query = {read=GetStringVariable, index=3};

Description

Read Query to determine the details of a query specified in the URL of the Web client request. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the Query portion is:

animal=dog&color=black

Query is the unparsed query portion of the URL. The query may include multiple fields separated by ampersands. Use the QueryFields property to work with the query on a field-by-field basis.


TCGIRequest::Referer

TCGIRequest	See also

Represents the value of the Referer header of the HTTP request message.

__property System::AnsiString Referer = {read=GetStringVariable, index=12};

Description

Read Referer to determine the URI of the resource where the HTTP request message originated. Referer allows the server application to generate back-links to the source of the request. If Referer is a partial URI, it should be interpreted as a relative path to the URL property.

The Referer property is not set when the URL of the HTTP request was obtained from a source that does not have its own URI, such as input from the user keyboard.


TCGIRequest::RemoteAddr

TCGIRequest	See also

Indicates the remote IP address of the client associated with the HTTP request message.

__property System::AnsiString RemoteAddr = {read=GetStringVariable, index=21};

Description

Read RemoteAddr to obtain the IP address of the source of the Web client request.


TCGIRequest::RemoteHost

TCGIRequest	See also

Represents the fully qualified reverse domain lookup of the client associated with the HTTP request message.

__property System::AnsiString RemoteHost = {read=GetStringVariable, index=22};

Description

Use RemoteHost to compose URI values for back-links to the source of the request when the Referer property is not specified. RemoteHost does not include any path information.


TCGIRequest::ScriptName

TCGIRequest	See also

Indicates the value of the script information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString ScriptName = {read=GetStringVariable, index=23};

Description

Read ScriptName to determine the full path to the Web server application specified by the client request. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the ScriptName portion is

/art/gallery


TCGIRequest::ServerPort

TCGIRequest	See also

Indicates the number of the port on the Web server that receives the HTTP request message.

__property int ServerPort = {read=GetIntegerVariable, index=24, nodefault};

Description

Read ServerPort to determine the number of the port used in the connection to the Web server. The Host property will include the ServerPort if it is specified as part of the URL for the client request.


TCGIRequest::Title

TCGIRequest	See also

Represents the value of the Title header of the HTTP request message.

__property System::AnsiString Title = {read=GetStringVariable, index=20};

Description

Read Title to determine the Title of the information requested in the Web client request.


TCGIRequest.URL

TCGIRequest	See also

Indicates the Uniform Resource Identifier (URI) specified by the HTTP request message to identify the target of the request.

__property System::AnsiString URL = {read=GetStringVariable, index=2};

Description

Use the URL property to identify the resource the Web client identifies as the target of the request message. URL may be an HTML page to return, a resource to be created or deleted, or an object that provides some other service for the Web client.

The TCGIRequest object parses the URL into its constituent parts, yielding the Host property, the ScriptName property, the PathInfo property, and the Query property.

Note:	Usually the URL property is a Uniform Resource Locator (URL) that can be parsed into host, script, path, and query portions. However, it is possible for HTTP request messages to specify the target in more general terms, as a Uniform Resource Identifier (URI).


TCGIRequest::UserAgent

TCGIRequest	See also

Represents the value of the User-Agent header of the HTTP request message.

__property System::AnsiString UserAgent = {read=GetStringVariable, index=13};

Description

Read UserAgent to obtain information about the user agent originating the client request. Use the UserAgent information for statistical purposes, for tracing protocol violations, and for tailoring responses to known limitations of specific applications that generate client requests. The UserAgent string contains one or more descriptors, in order of significance. Each descriptor gives the name of the product or application that generated the request, or a comment about the user agent.


TCGIRequest methods

TCGIRequest	Alphabetically	Legend

In TCGIRequest

~TCGIRequest

GetDateVariable

GetFieldByName

GetIntegerVariable

GetStringVariable

ReadClient

ReadString

TCGIRequest

TranslateURI

WriteClient

WriteString

Derived from TWebRequest

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCGIRequest methods

TCGIRequest	By object	Legend

~TCGIRequest

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

FieldAddress

Free

FreeInstance

GetDateVariable

GetFieldByName

GetIntegerVariable

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadClient

ReadString

SafeCallException

TCGIRequest

TranslateURI

WriteClient

WriteString


TCGIRequest::TCGIRequest

TCGIRequest	See also

Creates an instance of TCGIRequest.

__fastcall TCGIRequest(void);

Description

Applications shouldn’t need to directly instantiate a CGI request object. The TCGIApplication object creates a TCGIRequest object whenever it receives a client request.


TCGIRequest::GetDateVariable

TCGIRequest	See also

Extracts a date value from the internal table of HTTP header variables.

virtual System::TDateTime __fastcall GetDateVariable(int Index);

Description

GetDateVariable reads date-time values from the header strings of the HTTP request message. The CGI request object uses GetDateVariable to access the properties that represent dates from the HTTP request headers.


TCGIRequest::GetFieldByName

TCGIRequest	See also

Returns the value of the HTTP header variable specified by the Name parameter.

virtual System::AnsiString __fastcall GetFieldByName(const System::AnsiString Name);

Description

Use GetFieldByName to read the value of an HTTP header variable that is not surfaced as one of the properties of TCGIRequest. For information on possible HTTP request header variables, see the current Internet standards documents.


TCGIRequest::GetIntegerVariable

TCGIRequest	See also

Extracts an integer value from the internal table of HTTP header variables.

virtual int __fastcall GetIntegerVariable(int Index);

Description

GetIntegerVariable reads integer values from the header strings of the HTTP request message. The CGI request object uses GetIntegerVariable to access the properties that represent integers from the HTTP request headers.


TCGIRequest::GetStringVariable

TCGIRequest	See also

Extracts a string value from the internal table of HTTP header variables.

virtual System::AnsiString __fastcall GetStringVariable(int Index);

Description

GetStringVariable reads string values from the header strings of the HTTP request message. The CGI request object uses GetStringVariable to access the properties that represent strings from the HTTP request headers.


TCGIRequest::ReadClient

TCGIRequest	See also

Reads Count bytes from the HTTP request into Buffer.

virtual int __fastcall ReadClient(void *Buffer, int Count);

Description

Use ReadClient to load a chunk of information from the contents of an HTTP request into a buffer. ReadClient allows the server application to get the next chunk of information when the content of the request message is too large for the Content property. ReadClient returns the number of bytes actually read. If no more content is available, ReadClient returns -1.


TCGIRequest::ReadString

TCGIRequest	See also

Reads Count bytes from the HTTP request into a string.

virtual System::AnsiString __fastcall ReadString(int Count);

Description

Use ReadString to load the next chunk of content information form the HTTP request into a string. ReadString allows the server application to get the next chunk of information when the content of the request message is too large for the Content property.


TCGIRequest::TranslateURI

TCGIRequest	See also

Takes the place of a method for translating URIs into a format usable by the server.

virtual System::AnsiString __fastcall TranslateURI(const System::AnsiString URI);

Description

TranslateURI is used with HTTP request objects to translate the URI specified in a client request into a format that can be used by the server application. As CGI applications work directly with URI values, no translation is necessary.


TCGIRequest::WriteClient

TCGIRequest	See also

Writes Count bytes from Buffer back to the HTTP client.

virtual int __fastcall WriteClient(void *Buffer, int Count);

Description

Use WriteClient to write the contents of a response back to the Web client.  Most applications do not need to use the WriteClient method, because the CGI application object automatically sends the TCGIResponse object back to the client.


TCGIRequest::WriteString

TCGIRequest	See also

Writes the string AString back to the HTTP client.

virtual bool __fastcall WriteString(const System::AnsiString AString);

Description

Use WriteString to write the contents of a response back to the Web client.  Most applications will not need to use WriteString, because the CGI application object automatically sends the TCGIResponse object back to the client.


TCGIRequest::~TCGIRequest

TCGIRequest

Frees the memory associated with the TCGIRequest object.

__fastcall virtual ~TCGIRequest(void) { }

Description

Do not call ~TCGIRequest directly. Instead, use the delete keyword on the object, which causes ~TCGIRequest to be invoked automatically.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TWebRequest


TCGIResponse

Hierarchy	Properties	Methods	See also

TCGIResponse represents HTTP messages sent by a CGI application in response to an HTTP request message.

Unit

cgiapp

Description

Use TCGIResponse to specify the response to an HTTP request message in a CGI application.

The CGI application creates a TCGIResponse object based on the TCGIRequest object for an incoming web client request message. The TWebDispatcher for the application then passes the TCGIResponse object to the TWebActionItem associated with the TCGIRequest object. The TWebActionItem sets the properties of the TCGIResponse object.


TCGIResponse properties

TCGIResponse	Alphabetically	Legend

In TCGIResponse

Allow

Content

ContentEncoding

ContentLength

ContentType

ContentVersion

Date

DerivedFrom

Expires

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate

Derived from TWebResponse

ContentStream

Cookies

CustomHeaders

HTTPRequest


TCGIResponse properties

TCGIResponse	By object	Legend

Allow

Content

ContentEncoding

ContentLength

ContentStream

ContentType

ContentVersion

Cookies

CustomHeaders

Date

DerivedFrom

Expires

HTTPRequest

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate


TCGIResponse::Allow

TCGIResponse	See also

Lists the HTTP request methods that the application can service.

__property System::AnsiString Allow = {read=GetStringVariable, write=SetStringVariable, index=5};

Description

Use Allow to indicate what type of request methods the server application can respond to for the URL specified in the HTTPRequest. Allow is a string of method names, separated by commas. The method names can include any pre-defined methods from the HTTP standard, or any additional methods implemented by the server application. At a minimum, the TCGIResponse object must allow GET and HEAD requests.


TCGIResponse::Content

TCGIResponse	See also 	Example

Contains the information sent to the web client in response to an HTTP request message.

__property System::AnsiString Content = {read=GetContent, write=SetContent};

Description

Use Content to send requested information to the web client. Not every HTTP request message requires content to be returned. For example, responses to requests with a Method of OPTIONS, HEAD, POST, PUT, DELETE, or TRACE should not include any Content. In all these cases, the response information is contained entirely in the response header, which is built from the other properties of the TCGIResponse object.

The response content can be a string of HTML commands, the name of an HTML file, graphic content such as a bit-stream, or any other MIME content type.

Note:	If the ContentStream property is set, it supersedes the value of the Content property. If both Content and ContentStream are set, the web client is sent the value of the ContentStream, not the value of the Content property.


TCGIResponse::ContentEncoding

TCGIResponse	See also

Lists the mechanisms, if any, that are used to encode the content of the HTTP response message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, write=SetStringVariable, index=7 };

Description

Set ContentEncoding when the value of the Content has been encoded before it is sent to the web client. The encoding mechanisms are listed in the order in which they are applied, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding method used to transfer extended-ascii characters over the net.


TCGIResponse::ContentLength

TCGIResponse	See also

Specifies the length, in bytes, of the Content property.

__property int ContentLength = {read=GetIntegerVariable, write=SetIntegerVariable, index=0, nodefault };

Description

Set ContentLength to the length of the Content property, if it is known. If the length of the Content property is unknown, or if the HTTP response message does not include any content, set ContentLength to 0. Web clients use the ContentLength when reading the contents of the HTTP response message.

If the contents of the response message are taken from a stream, the value of ContentLength is set from the stream.


TCGIResponse::ContentType

TCGIResponse	See also

Specifies the value of the media type of the Content of the HTTP response message.

__property System::AnsiString ContentType = {read=GetStringVariable, write=SetStringVariable, index=8 };

Description

Set ContentType to indicate the media type of the Content of the HTTP response message. The value of ContentType must specify a valid MIME content type. The ContentType string has the form Type/SubType.

For example, if the response message sends a string of HTML commands to the web client in response to a GET request, the ContentType is text/html.

Note:	If the HTTP request message includes an Accept header, ContentType should be one of the content types listed in the TCGIRequest::Accept property.


TCGIResponse::ContentVersion

TCGIResponse	See also

Represents the version associated with the Content of the HTTP response message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, write=SetStringVariable, index=9 };

Description

Use ContentVersion to specify a version associated with the Content of the HTTP response. The meaning of ContentVersion depends on the type of information that is sent in the HTTP response. For example, if the Content of the HTTP response has a ContentType of text/html, ContentVersion would be the version of HTML used.

Server applications that introduce meanings for the ContentVersion property should document the interpretation they assign to ContentVersion.


TCGIResponse::Date

TCGIResponse	See also

Indicates the time and date when the HTTP response message is sent to the web client.

__property System::TDateTime Date = {read=GetDateVariable, write=SetDateVariable, index=0};

Description

Set Date to the current date and time immediately before sending the HTTP response message to the web client. Date is used by the web client to determine the age of the information returned.

Date is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TCGIResponse::DerivedFrom

TCGIResponse	See also

Specifies the URI of the resource where the Content of the HTTP response originated.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, write=SetStringVariable, index=10 };

Description

Set DerivedFrom to the URI where the value of Content originates. It is especially important to set DerivedFrom when the Content of the HTTP response did not originate from the resource indicated by the URL property of the HTTP request message.


TCGIResponse::Expires

TCGIResponse	See also

Specifies the date and time after which the Content of the HTTP response message should be considered invalid.

__property System::TDateTime Expires = {read=GetDateVariable, write=SetDateVariable, index=1};

Description

Set Expires when the Content of the HTTP response message contains information that may become invalid with the passage of time. Setting an Expires value does not imply that the information or its source will necessarily change or cease to exist when the Expires date and time is reached. Web clients are simply warned to check the freshness of the information after the Expires date and time.

The value of Expires is specified in the local time of the machine. The HTTP response message translates this value to the date encoding used by HTTP.

Expires is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TCGIResponse::LastModified

TCGIResponse	See also

Indicates the date and time that the value of the Content property was last updated.

__property System::TDateTime LastModified = {read=GetDateVariable, write=SetDateVariable, index=2};

Description

Set LastModified to indicate the last time the Content of the HTTP response was modified. This allows web clients to determine whether their local version of that information is up-to-date. When the HTTP request is a HEAD message, this may allow the web client and server to skip a potentially expensive transfer of information.

The value of LastModified is specified in the local time of the machine. The HTTP response message translates this value to the date encoding used by HTTP.

LastModified is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TCGIResponse::Location

TCGIResponse	See also

Specifies the URI of a resource the web client should point to for the completion of its request.

__property System::AnsiString Location = {read=GetStringVariable, write=SetStringVariable, index=6};

Description

Set Location when the HTTPResponse created a new resource in response to the HTTP request message, or when the servicing of the response must be delegated to another URI than the one specified in the HTTP request message.


TCGIResponse::LogMessage

TCGIResponse	See also

Describes the HTTP response message for event logging purposes.

__property System::AnsiString LogMessage = {read=GetLogMessage, write=SetLogMessage};

Description

Set LogMessage to a description of the action carried out by the TWebActionItem object that services this HTTP response. Usually, LogMessage includes the URI that handled the HTTP request message, along with date and time information.


TCGIResponse::Realm

TCGIResponse	See also

Indicates the set of protected-access URIs that includes the URL specified by the HTTP request message.

__property System::AnsiString Realm = {read=GetStringVariable, write=SetStringVariable, index=4};

Description

Set Realm when the HTTP response message returns 401 (Unauthorized) or 402 (Payment required). Realm is the name of a set of URIs that require a password or payment before the web client can access them. All the URIs in the realm, including the URL specified in the HTTP request message, are made available as soon as the web client provides the password or payment for the realm. The server application should keep track, internally, of the passwords or payments the client has provided, using the client information provided by the THTTPRequest object.


TCGIResponse::ReasonString

TCGIResponse	See also

Indicates the status of the response to the web client request.

__property System::AnsiString ReasonString = {read=GetStringVariable, write=SetStringVariable, index=1 };

Description

Set ReasonString to inform the human web client of the success or failure of the HTTP request message. Each reason string is associated with a 3-digit status code whose value indicates the status of the response. The HTTP standard defines a number of stock status codes and corresponding reason strings. In addition, server applications can define new reason strings and associate them with unused status codes.


TCGIResponse::Server

TCGIResponse	See also

Provides information about the software used by the server application to handle the request.

__property System::AnsiString Server = {read=GetStringVariable, write=SetStringVariable, index=2};

Description

Set Server to a string giving the name and version number of the application that provides the Content of the HTTP response message. The value of Server can contain multiple product identifiers and comments, listed in order of significance and separated by spaces. Product identifiers take the form Product Name/Version Number.


TCGIResponse::StatusCode

TCGIResponse	See also

Indicates the status of the response to the HTTP request message as a 3-digit integer.

__property int StatusCode = {read=GetStatusCode, write=SetStatusCode, nodefault};

Description

Set StatusCode to inform the web client the status of the HTTP request message. Status codes are standard return values that can be interpreted by all web clients. Each status code has a corresponding reason string that provides a human web client with a more understandable indication of the status.

The following tables lists the available status codes and their corresponding reason strings.

StatusCode	ReasonString

100	Continue

101	Switching Protocols

200	OK

201	Created

202	Accepted

203	Non-Authoritative Information

204	No Content

205	Reset Content

206	Partial Content

300	Multiple Choices

301	Moved Permanently

302	Moved Temporarily

303	See Other

304	Not Modified

305	Use Proxy

400	Bad Request

401	Unauthorized

402	Payment Required

403	Forbidden

404	Not Found

405	Method Not Allowed

406	Not Acceptable

407	Proxy Authentication Required

408	Request Time-out

409	Conflict

410	Gone

411	Length Required

412	Precondition Failed

413	Request Entity Too Large

414	Request-URI Too Large

415	Unsupported Media Type

500	Internal Server Error

501	Not Implemented

502	Bad Gateway

503	Service Unavailable

504	Gateway Time-out

505	HTTP Version not supported

Status codes not in the table can be created by the server application. When creating a new status code, the most significant digit should indicate the class of response, as follows:

•	1xx: Informational (request received, continuing process)

•	2xx: Success (request received, understood, and accepted)

•	3xx: Redirection (further action needed to complete the request)

•	4xx: Client Error (request contains bad syntax or cannot be serviced)

•	5xx: Server Error (server failed to handle a valid request)


TCGIResponse::Title

TCGIResponse	See also

Specifies a title for the Content of the HTTP response message.

__property System::AnsiString Title = {read=GetStringVariable, write=SetStringVariable, index=11};

Description

Set the Title property to add a Title header to the HTTP response message. Title is an optional application-specific title associated with the information included in the message.


TCGIResponse::Version

TCGIResponse	See also

Indicates the HTTP protocol version number that the web client is using.

__property System::AnsiString Version = {read=GetStringVariable, write=SetStringVariable, index=0};

Description

Read Version to ensure that the properties set in the TCGIResponse object will be understood by the web client. The value of Version is taken from the ProtocolVersion property of the HTTPRequest property.

For more information on the different HTTP protocol versions, see the Internet standards documentation available on the home page of the World Wide Web Consortium <http://www.w3.org>.


TCGIResponse::WWWAuthenticate

TCGIResponse	See also

Lists one or more comma-separated challenges provided when the request fails with StatusCode 401 (Unauthorized).

__property System::AnsiString WWWAuthenticate = {read=GetStringVariable, write=SetStringVariable, index=3 };

Description

Set WWWAuthenticate when the HTTP request fails because it requires access to a URI in a realm for which the web client has not provided a password. WWWAuthenticate consists of an authentication scheme name, followed by a comma-separated list of parameter/value pairs that specify the parameters to the authentication scheme. The first parameter/value pair indicates the realm.

For more information about HTTP authentication schemes, see the Internet standards documentation.


TCGIResponse methods

TCGIResponse	Alphabetically	Legend

In TCGIResponse

~TCGIResponse

GetContent

GetDateVariable

GetIntegerVariable

GetLogMessage

GetStatusCode

GetStringVariable

SendRedirect

SendResponse

SendStream

Sent

SetContent

SetDateVariable

SetIntegerVariable

SetLogMessage

SetStatusCode

SetStringVariable

TCGIResponse

Derived from TWebResponse

GetCustomHeader

SetCookieField

SetCustomHeader

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCGIResponse methods

TCGIResponse	By object	Legend

~TCGIResponse

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetContent

GetCustomHeader

GetDateVariable

GetIntegerVariable

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLogMessage

GetStatusCode

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

SendRedirect

SendResponse

SendStream

Sent

SetContent

SetCookieField

SetCustomHeader

SetDateVariable

SetIntegerVariable

SetLogMessage

SetStatusCode

SetStringVariable

TCGIResponse


TCGIResponse::TCGIResponse

TCGIResponse	See also

Creates an instance of TCGIResponse to represent the response to the HTTPRequest parameter.

__fastcall TCGIResponse(Httpapp::TWebRequest* HTTPRequest);

Description

Applications shouldn’t need to directly instantiate a CGI response object. The TCGIApplication object creates a TCGIResponse for each TCGIRequest it creates.


TCGIResponse::GetContent

TCGIResponse	See also

Reads the value of the Content property.

virtual System::AnsiString __fastcall GetContent(void);

Description

GetContent is the protected access function for the Content property.


TCGIResponse::GetDateVariable

TCGIResponse	See also

Extracts a date from the internal table of HTTP header variables.

virtual System::TDateTime __fastcall GetDateVariable(int Index);

Description

The CGI response object uses GetDateVariable to access the properties that represent dates.


TCGIResponse::GetIntegerVariable

TCGIResponse	See also

Extracts an integer value from the internal table of HTTP header variables.

virtual int __fastcall GetIntegerVariable(int Index);

Description

The CGI response object uses GetIntegerVariable to access the properties that represent integers.


TCGIResponse::GetLogMessage

TCGIResponse	See also

Reads the value of the LogMessage property.

virtual System::AnsiString __fastcall GetLogMessage(void);

Description

GetLogMessage is the protected access function for LogMessage property.


TCGIResponse::GetStatusCode

TCGIResponse	See also

Reads the value of the StatusCode property.

virtual int __fastcall GetStatusCode(void);

Description

GetStatusCode is the protected access function for the StatusCode property.


TCGIResponse::GetStringVariable

TCGIResponse	See also

Extracts a string value from the internal table of HTTP header variables.

virtual System::AnsiString __fastcall GetStringVariable(int Index);

Description

The CGI response object uses GetStringVariable to access the properties that represent strings.


TCGIResponse::SendRedirect

TCGIResponse	See also

Sends the response with a StatusCode of 301 (Moved Permanently) and with Location set to the URI parameter.

virtual void __fastcall SendRedirect(const System::AnsiString URI);

Description

Call SendRedirect to redirect the web client request to another URI that is the proper target of the request. SendRedirect does the same thing as setting the StatusCode to 301, the Location to URI, and calling SendResponse.


TCGIResponse::SendResponse

TCGIResponse	See also

Sends the CGI response message to the web client.

virtual void __fastcall SendResponse(void);

Description

Call SendResponse after setting the properties of the CGI response object to specify the response that should be sent to the web client. If the request should be redirected to another URI, it is more efficient to call SendRedirect.


TCGIResponse::SendStream

TCGIResponse	See also

Sends the CGI response message with the contents set to the contents of AStream.

virtual void __fastcall SendStream(Classes::TStream* AStream);

Description

Only call SendStream after first calling SendResponse. Unlike SendStream, SendResponse fills the header of the HTTP response message, based on the properties of the TCGIResponse object. If SendResponse has not been called first to set the header of the HTTP response message, set the ContentStream property to AStream, and call SendResponse.


TCGIResponse::Sent

TCGIResponse	See also

Indicates whether the CGI response message has already been sent.

virtual bool __fastcall Sent(void);

Description

Sent returns true if the SendRedirect or SendStream method has been called. TCGIApplication calls Sent so that it knows when to send unsent responses to the web client.


TCGIResponse::SetContent

TCGIResponse	See also

Sets the Content property.

virtual void __fastcall SetContent(const System::AnsiString Value);

Description

SetContent is the protected method used by CGI response objects to set the Content property.


TCGIResponse::SetDateVariable

TCGIResponse	See also

Sets a date-time valued HTTP header property.

virtual void __fastcall SetDateVariable(int Index, const System::TDateTime Value);

Description

SetDateVariable writes date-time to the internal table used to store HTTP header variables. The CGI response object uses SetDateVariable to set the properties that represent dates.


TCGIResponse::SetIntegerVariable

TCGIResponse	See also

Sets an integer valued HTTP header property.

virtual void __fastcall SetIntegerVariable(int Index, int Value);

Description

SetIntegerVariable writes integer values to the internal table used to store HTTP header variables. The CGI response object uses SetIntegerVariable to set the properties that represent integers.


TCGIResponse::SetLogMessage

TCGIResponse	See also

Sets the value of the LogMessage property.

virtual void __fastcall SetLogMessage(const System::AnsiString Value);

Description

SetLogMessage is the protected method used by CGI response objects to set the LogMessage property.


TCGIResponse::SetStatusCode

TCGIResponse	See also

Sets the StatusCode property.

virtual void __fastcall SetStatusCode(int Value);

Description

SetStatusCode is the protected method used by CGI response objects to set the StatusCode property.


TCGIResponse::SetStringVariable

TCGIResponse	See also

Sets a string valued HTTP header property.

virtual void __fastcall SetStringVariable(int Index, const System::AnsiString Value);

Description

SetStringVariable writes string values to the internal table used to store HTTP header variables. The CGI response object uses SetStringVariable to set the properties that represent strings.


Accessibility

Read-only


TCGIResponse::~TCGIResponse

TCGIResponse

Frees the memory associated with the TCGIResponse object.

__fastcall virtual ~TCGIResponse(void) { }

Description

Do not call ~TCGIResponse directly. Instead, use the delete keyword on the object, which causes ~TCGIResponse to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TWebResponse


TWinCGIRequest

Hierarchy	Properties	Methods	See also

TWinCGIRequest represents client request information that is passed to a Windows hosted CGI Web server application.

Unit

cgiapp

Description

Use TWinCGIRequest to interpret a client request to a Windows hosted CGI Web server application.

CGI application objects create TWinCGIRequest objects to capture client requests. The properties of the TWinCGIRequest objects are obtained from the Web server. The CGI application uses TWinCGIRequest objects to create corresponding TWinCGIResponse objects. The TWebDispatcher object for the application then invokes the TWebActionItem that is associated with the path portion of the URL of the TWinCGIRequest object.


TWinCGIRequest properties

TWinCGIRequest	Alphabetically	Legend

In TWinCGIRequest

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentType

ContentVersion

Cookie

DerivedFrom

From

Host

Method

PathInfo

PathTranslated

ProtocolVersion

Query

Referer

RemoteAddr

RemoteHost

ScriptName

Title

URL

UserAgent

Derived from TCGIRequest

ContentLength

Date

Expires

IfModifiedSince

ServerPort

Derived from TWebRequest

ContentFields

CookieFields

MethodType

QueryFields


TWinCGIRequest properties

TWinCGIRequest	By object	Legend

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentFields

ContentLength

ContentType

ContentVersion

Cookie

CookieFields

Date

DerivedFrom

Expires

From

Host

IfModifiedSince

Method

MethodType

PathInfo

PathTranslated

ProtocolVersion

Query

QueryFields

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent


TWinCGIRequest::Accept

TWinCGIRequest	See also

Represents the value of the Accept header of the HTTP request message.

__property System::AnsiString Accept = {read=GetStringVariable, index=8};

Description

Read Accept to determine the media types the Web client can accept in response to the request. Not every HTTP request message has an Accept header. If the Accept property is not set, then any media type is potentially acceptable in the response.

Accept headers usually indicate that the response should be limited to a small set of desired types. For example, a Web client requesting an audio response might produce a TWinCGIRequest object with Accept set to the following string:

audio/*; q=0.2, audio/basic

This request indicates that the preferred response media type is audio/basic, but that any audio type is acceptable if it is the best available after an 80% mark-down in quality.

For information on the format of Accept headers, see the current Internet standards documentation.


TWinCGIRequest::Authorization

TWinCGIRequest	See also

Represents the value of the Authorization header of the HTTP request message.

__property System::AnsiString Authorization = {read=GetStringVariable, index=28};

Description

Read Authorization to check whether the client that sent the request message has provided the correct authentication information. Authorization allows the CGI application to provided limited access to the resource specified by the URL property.

For more information about HTTP authentication schemes, see the Internet standards documentation.


TWinCGIRequest::CacheControl

TWinCGIRequest 	See also

Represents the value of the Cache-Control header of the HTTP request message.

__property System::AnsiString CacheControl = {read=GetStringVariable, index=6};

Description

Read CacheControl to determine any Web client directives that must be obeyed by all caching mechanisms along the request/response chain. The CacheControl directives of the HTTP request do not need to apply to the corresponding HTTP response.

The HTTP 1.1 standard defines the following directives for CacheControl:

Value	Meaning

no-cache	The request may not be cached. The Web server validates the request before the TWinCGIRequest object is created.

no-store	The request contains sensitive information and may not be stored on any permanent medium such as a back-up tape. If the request is stored temporarily in a file, the file must be deleted.

max-age=ss	The request is considered invalid if it is older than ss seconds. This directive takes precedence over the Expires property, even if Expires is more restrictive. Invalid requests are validated by the Web server before the TWinCGIRequest object is created.

max-stale or max-stale=ss	The client is willing to accept a response that has exceeded it’s expiration time. The max-stale directive can optionally specify the number of seconds by which the response can exceed it’s expiration time.

 min-fresh=ss	The client is not willing to accept a response that expires in less than ss seconds.


TWinCGIRequest::Connection

TWinCGIRequest	See also

Represents the value of the Connection header of the HTTP request message.

__property System::AnsiString Connection = {read=GetStringVariable, index=26};

Description

Read Connection to determine the options requested by the Web client for its connection to the server application. The HTTP 1.1 standard specifies only one value for the Connection header. If the value of Connection is close, then the connection should be closed after the completion of the response.


TWinCGIRequest::Content

TWinCGIRequest	See also

Represents the unparsed contents of the HTTP request message.

__property System::AnsiString Content = {read=GetStringVariable, index=25};

Description

Use Content to read the contents of an HTTP request message that is sending information to the server. The value of Content depends on the Method of the HTTP request. When the Method is POST, Content is the unparsed string giving the values to be posted with their associated fields. When the Method is PUT, Content is the value that should replace the URL given by the URL property.

Note:	When the Method is POST, the parsed version of the post request is available in the ContentFields property.


TWinCGIRequest::ContentEncoding

TWinCGIRequest	See also

Represents the value of the Content-Encoding header of the HTTP request message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, index=14};

Description

Read ContentEncoding to determine what encoding mechanisms, if any, have been applied to the Content of the HTTP request. The encoding mechanisms are listed in the order in which they were applied by the Web client, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding scheme used to transfer extended-ascii characters over the net.

Reverse the ContentEncoding mechanisms to decode the Content into the form indicated by the ContentType property.


TWinCGIRequest::ContentType

TWinCGIRequest	See also

Represents the value of the Content-Type header of the HTTP request message.

__property System::AnsiString ContentType = {read=GetStringVariable, index=15};

Description

Read ContentType to determine the media type of the Content of the HTTP request message. The ContentType is a string of the form Type/SubType.

Most HTTP requests do not require any Content at all. For most requests with a Method that requires a value for Content, the ContentType is text/html. However, HTTP requests for server-specific values of Method can use any media type appropriate to the request.


TWinCGIRequest::ContentVersion

TWinCGIRequest	See also

Represents the value of the Content-Version header of the HTTP request message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, index=17};

Description

Read ContentVersion to determine the version of the Content of the HTTP request message. Most HTTP requests do not require any Content at all. When the Method requires a value for Content, the ContentVersion may be set to indicate the version of the source of that content. The format of the ContentVersion depends on the ContentType of the request.


TWinCGIRequest::Cookie

TWinCGIRequest	See also

Represents the value of the Cookie header of the HTTP request message.

__property System::AnsiString Cookie = {read=GetStringVariable, index=27};

Description

Use Cookie to read the “cookie” strings provided in the Web client request. Cookie strings are generally used to track state information in a Web application. Usually the value is passed on from a cookie header sent in a previous response message.

Cookie is the unparsed value of the Cookie header. The Cookie header can include multiple fields separated by semicolons (;). Use the CookieFields property to work with the Cookie header on a field-by-field basis.


TWinCGIRequest::DerivedFrom

TWinCGIRequest	See also

Represents the value of the Derived-From header of the HTTP request message.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, index=18};

Description

Read DerivedFrom to determine the URI where the value of Content originated. DerivedFrom is only meaningful when the request includes a Content property and the Content did not originate with the Web client.


TWinCGIRequest::From

TWinCGIRequest	See also

Represents the value of the From header of the HTTP request message.

__property System::AnsiString From = {read=GetStringVariable, index=9};

Description

Read From to determine the Internet e-mail address of the human user for whom the Web client sent the HTTP request message. This value can be used for logging purposes, or to contact the originator of the request if problems occur.


TWinCGIRequest::Host

TWinCGIRequest	See also

Represents the value of the Host header of the HTTP request message.

__property System::AnsiString Host = {read=GetStringVariable, index=10};

Description

Read Host to determine the Internet host and port number of resource being requested. For example, if the client request specifies the following URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

The value of Host would be

www.TSite.com

The value of Host can be used to differentiate between internally-ambiguous URLs, such as the root “/” URL of a server for multiple host names on a single IP address.


TWinCGIRequest::Method

TWinCGIRequest	See also

Represents the value of the Method header of the HTTP request message.

__property System::AnsiString Method = {read=GetStringVariable, index=0};

Description

Read Method to determine the method that is requested by the Web client. The HTTP 1.1 standard defines the following methods

Value	Meaning

OPTIONS	A request for information about available communication options.

GET	A request for the information identified by the URL property.

HEAD	A request for information about the properties of the HTTP response, but not for the content of the response.

POST	A request for the server application to post the data included in the Content property, as appropriate.

PUT	A request for the server application to replace the resource indicated by the URL property with the data included in the Content property.

DELETE	A request for the server application to delete or hide the resource identified by the URL property.

TRACE	A request for the server application to send a loop-back to confirm receipt of the request.

The Method property may indicate any other method that the Web client requests of the server. If the Method can’t be matched to the Allow property of a TCGIResponse object, the request can’t be serviced.

The MethodType property indicates whether the value of Method is GET, HEAD, POST, PUT, or one of the other strings. When possible, use MethodType instead of the Method property, to save the overhead of string comparison.

Note:	A CGI application does not need to service all method types. However, there must be a response for the GET and HEAD method requests.


TWinCGIRequest::PathInfo

TWinCGIRequest	See also

Represents the value of the path information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString PathInfo = {read=GetStringVariable, index=4};

Description

Read PathInfo to determine the path on the server machine where the target of the request is found. For example, given this URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the PathInfo portion is:

/mammals

The TWebDispatcher object uses the PathInfo to identify the appropriate TWebActionItem for servicing the request message.


TWinCGIRequest::PathTranslated

TWinCGIRequest	See also

Represents a translation of the PathInfo property to a fully qualified path on the Web server.

__property System::AnsiString PathTranslated = {read=GetStringVariable, index=5};

Description

Use PathTranslated to refer to the location of the target of the request in an HTTP response.


TWinCGIRequest::ProtocolVersion

TWinCGIRequest	See also

Indicates the version number of the HTTP protocol specified in the initial header of the HTTP request message.

__property System::AnsiString ProtocolVersion = {read=GetStringVariable, index=1};

Description

Use ProtocolVersion to determine the protocol used by the Web client when generating the HTTP request message.

Some properties of the HTTP request may be interpreted differently depending on the ProtocolVersion. For example, if ProtocolVersion is 1.0, then the connection should not be considered persistent, even if the Connection property does not specify the close option.


TWinCGIRequest::Query

TWinCGIRequest	See also

Represents the value of the query information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString Query = {read=GetStringVariable, index=3};

Description

Read Query to determine the details of a query specified in the URL of the Web client request. For example, given this URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the Query portion is:

animal=dog&color=black

Query is the unparsed query portion of the URL. The query may include multiple fields separated by ampersands (&). Use the QueryFields property to work with the query on a field-by-field basis.


TWinCGIRequest::Referer

TWinCGIRequest	See also

Represents the value of the Referer header of the HTTP request message.

__property System::AnsiString Referer = {read=GetStringVariable, index=12};

Description

Read Referer to determine the URI of the resource where the HTTP request message originated. Referer allows the server application to generate back-links to the source of the request. If Referer is a partial URI, it should be interpreted as a relative path to the URL property.

The Referer property is not set when the URL of the HTTP request was obtained from a source that does not have its own URI, such as input from the user keyboard.


TWinCGIRequest::RemoteAddr

TWinCGIRequest	See also

Indicates the remote IP address of the client associated with the HTTP request message.

__property System::AnsiString RemoteAddr = {read=GetStringVariable, index=21};

Description

Read RemoteAddr to obtain the IP address of the source of the Web client request.


TWinCGIRequest::RemoteHost

TWinCGIRequest	See also

Indicates the fully qualified reverse domain look-up of the client associated with the HTTP request message.

__property System::AnsiString RemoteHost = {read=GetStringVariable, index=22};

Description

Use RemoteHost to compose URI values for back-links to the source of the request when the Referer property is not specified. RemoteHost does not include any path information.


TWinCGIRequest::ScriptName

TWinCGIRequest	See also

Represents the value of the script information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString ScriptName = {read=GetStringVariable, index=23};

Description

Read ScriptName to determine the full path to the Web server application specified by the client request. For example, given this URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the ScriptName portion is:

/art/gallery


TWinCGIRequest::Title

TWinCGIRequest	See also

Represents the value of the Title header of the HTTP request message.

__property System::AnsiString Title = {read=GetStringVariable, index=20};

Description

Read Title to determine the Title of the information requested in the Web client request.


TWinCGIRequest.URL

TWinCGIRequest	See also

Indicates the Uniform Resource Identifier (URI) specified by the HTTP request message to identify the target of the request.

__property System::AnsiString URL = {read=GetStringVariable, index=2};

Description

Use the URL property to identify the resource the Web client identifies as the target of the request message. URL may be an HTML page to return, a resource to be created or deleted, or an object that provides some other service for the Web client.

The TWinCGIRequest object parses the URL into its constituent parts, yielding the Host property, the ScriptName property, the PathInfo property, and the Query property.

Note:	Usually the URL property is a Uniform Resource Locator (URL) that can be parsed into host, script, path, and query portions. However, it is possible for HTTP request messages to specify the target in more general terms, as a Uniform Resource Identifier (URI).


TWinCGIRequest::UserAgent

TWinCGIRequest	See also

Represents the value of the User-Agent header of the HTTP request message.

__property System::AnsiString UserAgent = {read=GetStringVariable, index=13};

Description

Read UserAgent to obtain information about the user agent originating the client request. Use the UserAgent information for statistical purposes, for tracing protocol violations, and for tailoring responses to known limitations of specific applications that generate client requests. The UserAgent string contains one or more descriptors, in order of significance. Each descriptor gives the name of the product or application that generated the request, or a comment about the user agent.


TWinCGIRequest methods

TWinCGIRequest	Alphabetically	Legend

In TWinCGIRequest

~TWinCGIRequest

GetFieldByName

GetStringVariable

ReadClient

ReadString

TranslateURI

TWinCGIRequest

WriteClient

WriteString

Derived from TWebRequest

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWinCGIRequest methods

TWinCGIRequest	By object	Legend

~TWinCGIRequest

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

FieldAddress

Free

FreeInstance

GetFieldByName

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadClient

ReadString

SafeCallException

TranslateURI

TWinCGIRequest

WriteClient

WriteString


TWinCGIRequest::TWinCGIRequest

TWinCGIRequest	See also

Creates an instance of TWinCGIRequest.

__fastcall TWinCGIRequest(System::AnsiString IniFileName, System::AnsiString ContentFile, System::AnsiString OutputFile);

Description

Applications don’t need to call TWinCGIRequest to instantiate a CGI request object. The TCGIApplication object creates a TWinCGIRequest object whenever it receives a client request.


TWinCGIRequest::~TWinCGIRequest

TWinCGIRequest	See also

Destroys an instance of TWinCGIRequest.

__fastcall virtual ~TWinCGIRequest(void);

Description

Do not call ~TWinCGIRequest. TCGIApplication destroys the TWinCGIRequest object after it is processed.

~TWinCGIRequest frees the internal structures used to manage the HTTP header variables.


TWinCGIRequest::GetFieldByName

TWinCGIRequest	See also

Returns the value of the HTTP header variable specified by the Name parameter.

virtual System::AnsiString __fastcall GetFieldByName(const System::AnsiString Name);

Description

Use GetFieldByName to read the value of an HTTP header variable that is not surfaced as one of the properties of TCGIRequest. For information on possible HTTP request header variables, see the current Internet standards documents.


TWinCGIRequest::GetStringVariable

TWinCGIRequest	See also

Extracts a string value from the internal table of HTTP header variables.

virtual System::AnsiString __fastcall GetStringVariable(int Index);

Description

GetStringVariable reads string values from the header strings of the HTTP request message. The CGI request object uses GetStringVariable to access the properties that represent strings from the HTTP request headers.


TWinCGIRequest::ReadClient

TWinCGIRequest	See also

Reads Count bytes from the HTTP request into Buffer.

virtual int __fastcall ReadClient(void *Buffer, int Count);

Description

Use ReadClient to load a chunk of information from the contents of an HTTP request into a buffer. ReadClient allows the server application to get the next chunk of information when the content of the request message is too large for the Content property. ReadClient returns the number of bytes actually read. If no more content is available, ReadClient returns -1.


TWinCGIRequest::ReadString

TWinCGIRequest	See also

Reads Count bytes from the HTTP request into a string.

virtual System::AnsiString __fastcall ReadString(int Count);

Description

Use ReadString to load the next chunk of content information form the HTTP request into a string. ReadString allows the server application to get the next chunk of information when the content of the request message is too large for the Content property.


TWinCGIRequest::TranslateURI

TWinCGIRequest	See also

Serves as a placeholder for a method that translates URIs for the server.

virtual System::AnsiString __fastcall TranslateURI(const System::AnsiString URI);

Description

TranslateURI is used with HTTP request objects to translate the URI specified in a client request into a format that can be used by the server application. As CGI applications work directly with URI values, no translation is necessary.


TWinCGIRequest::WriteClient

TWinCGIRequest	See also

Writes Count bytes from Buffer back to the HTTP client.

virtual int __fastcall WriteClient(void *Buffer, int Count);

Description

Use WriteClient to write the contents of a response back to the Web client.


TWinCGIRequest::WriteString

TWinCGIRequest	See also

Writes the string AString back to the HTTP client.

virtual bool __fastcall WriteString(const System::AnsiString AString);

Description

Use WriteString to write the contents of a response back to the Web client.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TWebRequest

TCGIRequest


TWinCGIResponse

Hierarchy	Properties	Methods	See also

TWinCGIResponse represents HTTP messages sent by a Windows hosted CGI application in response to an HTTP request message.

Unit

cgiapp

Description

Use TWinCGIResponse to specify the response to an HTTP request message.

A CGI application creates a TWinCGIResponse object based on the TWinCGIRequest object for an incoming web client request message. The Web dispatcher for the application then passes the TWinCGIResponse object to the TWebActionItem associated with the TWinCGIRequest object. The TWebActionItem sets the properties of the TWinCGIResponse object.


TWinCGIResponse properties

TWinCGIResponse	Alphabetically	Legend

Derived from TCGIResponse

Allow

Content

ContentEncoding

ContentLength

ContentType

ContentVersion

Date

DerivedFrom

Expires

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate

Derived from TWebResponse

ContentStream

CustomHeaders

HTTPRequest

Cookies


TWinCGIResponse properties

TWinCGIResponse	By object	Legend

Allow

Content

ContentEncoding

ContentLength

ContentStream

ContentType

ContentVersion

Cookies

CustomHeaders

Date

DerivedFrom

Expires

HTTPRequest

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate


TWinCGIResponse methods

TWinCGIResponse	Alphabetically

In TWinCGIResponse

~TWinCGIResponse

TWinCGIResponse

Derived from TWebResponse

GetCustomHeader

SetCookieField

SetCustomHeader

Derived from TCGIResponse

SendRedirect

SendResponse

SendStream

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWinCGIResponse methods

TWinCGIResponse	By object

~TWinCGIResponse

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetCustomHeader

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

SendRedirect

SendResponse

SendStream

SetCookieField

SetCustomHeader

TWinCGIResponse


TWinCGIResponse::TWinCGIResponse

TWinCGIResponse

Creates a new TWinCGIResponse object.

__fastcall TWinCGIResponse(Httpapp::TWebRequest* HTTPRequest) : Cgiapp::TCGIResponse(HTTPRequest) { }

Description

Do not create instances of TWinCGIResponse. They are created automatically by the TWinCGIApplication before dispatching incoming request messages.


TWinCGIResponse::~TWinCGIResponse

TWinCGIResponse

~TWinCGIResponse frees the memory associated with the TWinCGIResponse object.

__fastcall virtual ~TWinCGIResponse(void) { }

Description

Do not destroy instances of TWinCGIResponse. They are destroyed automatically by the TWinCGIApplication.


Accessibility

Read-only


Hierarchy

TObject

TWebResponse

TCGIResponse


TCheckConstraints

Hierarchy	Properties	Methods	See also

TCheckConstraints contains a collection of check constraints for a dataset component.

Unit

db

Description

BDE dataset components support check constraints that define the values that can be entered into a single record. The TCheckConstraints object maintains the collection of check constraints that apply to a given dataset.


TCheckConstraints properties

TCheckConstraints	Alphabetically	Legend

In TCheckConstraints

Items

Derived from TCollection

Count

ItemClass


TCheckConstraints properties

TCheckConstraints	By object	Legend

Count

ItemClass

Items


TCheckConstraints::Items

TCheckConstraints	See also

Maintains an indexed array of check constraints.

__property TCheckConstraint* Items[int Index] = {read=GetItem, write=SetItem};

Description

Use Items to access the check constraints that apply to the dataset component that owns this check constraint collection.


TCheckConstraints methods

TCheckConstraints	Alphabetically

In TCheckConstraints

~TCheckConstraints

Add

TCheckConstraints

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCheckConstraints methods

TCheckConstraints	By object

~TCheckConstraints

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCheckConstraints


TCheckConstraints.Add

TCheckConstraints	See also

Adds a check constraint item to the list maintained by this collection object.

HIDESBASE TCheckConstraint* __fastcall Add(void);

Description

Call Add to add another check constraint to those known to the dataset component that owns this check constraint object.


TCheckConstraints::TCheckConstraints

TCheckConstraints

Instantiates an instance of a check constraint collection object.

__fastcall TCheckConstraints(Classes::TPersistent* Owner);

Description

Call TCheckConstraints indirectly, using the new keyword, to instantiate a check constraint collection object at runtime when you need a collection object and it has not been created automatically for you. TCheckConstraints calls its parent class's constructor, and sets the collection’s owner object to Owner.


TCheckConstraints::~TCheckConstraints

TCheckConstraints

~TCheckConstraints frees the memory associated with the TCheckConstraints object.

__fastcall virtual ~TCheckConstraints(void) { }

Description

Do not call ~TCheckConstraints directly. Instead, use the delete keyword on the object, which causes ~TCheckConstraints to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


 TCheckBox

Hierarchy	Properties	Methods	Events	See also

TCheckBox represents a Windows check box.

Unit

stdctrls

Description

A TCheckBox component presents an option for the user. The user can check the box to select the option, or uncheck it to deselect the option.


TCheckBox properties

TCheckBox	Alphabetically	Legend

Derived from TCustomCheckBox

Alignment

AllowGrayed

Checked

State

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCheckBox properties

TCheckBox	By object	Legend

Alignment

Align

AllowGrayed

BoundsRect

Brush

Caption

Checked

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ControlCount

ControlState

Controls

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

Parent

ParentWindow

PopupMenu

ShowHint

Showing

State

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCheckBox events

TCheckBox	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TCheckBox events

TCheckBox	By object	Legend

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TCheckBox methods

TCheckBox	Alphabetically

In TCheckBox

~TCheckBox

TCheckBox

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCheckBox methods

TCheckBox	By object

~TCheckBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCheckBox

Update

UpdateControlState


TCheckBox::TCheckBox

TCheckBox

TCheckBox creates a new TCheckBox object.

__fastcall virtual TCheckBox(Classes::TComponent* AOwner) : Stdctrls::TCustomCheckBox(AOwner) { }

__fastcall TCheckBox(HWND ParentWindow) : Stdctrls::TCustomCheckBox(ParentWindow) { }

Description

Do not call TCheckBox directly. Instead, use the keyword new, which returns an indirect reference to the new check box. TCheckBox objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the check box with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the check box in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the check box is implemented as an ActiveX control.


TCheckBox::~TCheckBox

TCheckBox

~TCheckBox frees the memory associated with the TCheckBox object.

__fastcall virtual ~TCheckBox(void) { }

Description

Do not call ~TCheckBox directly. Instead, use the delete keyword on the object, which causes ~TCheckBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TButtonControl

TCustomCheckBox


TCheckBox example

TCheckBox


TCheckConstraint

Hierarchy	Properties	Methods

TCheckConstraint represents a check constraint on a dataset component.

Unit

db

Description

BDE dataset components implement a Constraints property that uses check constraints to represent record level constraints. These constraints can be derived from the server, the data dictionary, and can be customized in applications. Individual constraints associated with a dataset are represented by the TCheckConstraint object.


TCheckConstraint properties

TCheckConstraint	Alphabetically	Legend

In TCheckConstraint

CustomConstraint

ErrorMessage

FromDictionary

ImportedConstraint

Derived from TCollectionItem

Collection

DisplayName

ID

Index


TCheckConstraint properties

TCheckConstraint	By object	Legend

Collection

CustomConstraint

DisplayName

ErrorMessage

FromDictionary

ID

ImportedConstraint

Index


TCheckConstraint::CustomConstraint

TCheckConstraint	See also

Contains the SQL text representation of a constraint defined on a record by an application.

__property System::AnsiString CustomConstraint = {read=FCustomConstraint, write=SetCustomConstraint};

Description

Use CustomConstraint to store the SQL text that defines a check constraint defined by the application for a dataset component. Custom constraints are local to the application and do not get applied to the server when an application writes its changes to a database.


TCheckConstraint::ErrorMessage

TCheckConstraint	See also

Contains the text of an error message to display if data entered in a record by a user violates the constraint condition.

__property System::AnsiString ErrorMessage = {read=FErrorMessage, write=SetErrorMessage};

Description

Use ErrorMessage to set the error message string to display in an exception message dialog if a user enters data in a record that violates a check constraint condition.


TCheckConstraint::FromDictionary

TCheckConstraint	See also

Indicates whether or not to fetch a check constraint from the Data Dictionary.

__property bool FromDictionary = {read=FFromDictionary, write=FFromDictionary, nodefault};

Description

Use FromDictionary to indicate whether or not this check constraint should be derived from the Data Dictionary (true), or is local to the application (false).


TCheckConstraint::ImportedConstraint

TCheckConstraint	See also

Contains the SQL text for a check constraint imported from the Data Dictionary or a remote SQL database server.

__property System::AnsiString ImportedConstraint = {read=FImportedConstraint, write=SetImportedConstraint};

Description

Use ImportedConstraint to store the SQL text for a check constraint that is imported from the server or Data Dictionary. Although an application can set this property at runtime, ordinarily the text in ImportedConstraint is automatically provided to the application.


TCheckConstraint methods

TCheckConstraint	Alphabetically

In TCheckConstraint

~TCheckConstraint

Assign

GetDisplayName

TCheckConstraint

Derived from TCollectionItem

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCheckConstraint methods

TCheckConstraint	By object

~TCheckConstraint

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetDisplayName

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCheckConstraint


TCheckConstraint::Assign

TCheckConstraint

Assigns one constraint to another.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to read the SQL defining the check constraint from another TCheckConstraint object into this one. Source is the TCheckConstraint from which to read text.


TCheckConstraint::GetDisplayName

TCheckConstraint	See also

Retrieves the current text for a constraint.

virtual System::AnsiString __fastcall GetDisplayName();

Description

Call GetDisplayName to retrieve the current text for a check constraint. GetDisplayName attempts to read the current value of the ImportedConstraint property, unless it is an empty string. In that case it reads the current value of the CustomConstraint property. If it, too, is an empty string, then GetDisplayName calls its inherited GetDisplayName method.


TCheckConstraint::TCheckConstraint

TCheckConstraint	See also

Creates a new TCheckConstraint object.

__fastcall virtual TCheckConstraint(Classes::TCollection* Collection) : Classes::TCollectionItem(Collection) { }

Description

Most applications do not need to create check constraints directly. Instead, use the Add method of the associated TCheckConstraints object. Applications that create check constraints that are not managed by a TCheckConstraints object must use the new keyword.


TCheckConstraint::~TCheckConstraint

TCheckConstraint	See also

Frees the memory associated with the TCheckConstraint object.

__fastcall virtual ~TCheckConstraint(void) { }

Description

Do not call ~TCheckConstraint directly. Instead, use the delete keyword on the object, which causes ~TCheckConstraint to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


TChangeLink

Hierarchy	Properties	Methods	Events	See also

TImageList uses TChangeLink internally to notify other objects when changes are made to the image list.

Unit

controls

Description

A TImageList keeps a list of its TChangeLink objects. Each is associated with a particular component, such as a tree view or list view control. A component can register its change link with an image list by calling the image list’s RegisterChanges method. Before destruction, the component should then call the UnregisterChanges method.

Component writers can use the change link object to receive notification when changes are made to an image list that a control uses. Use the OnChange event of the change link to execute some code when the image list changes. For example, the tree view control uses a change link object to know when its image list has changed.


TChangeLink properties

TChangeLink	Alphabetically

In TChangeLink

Sender


TChangeLink properties

TChangeLink	By object

Sender


TChangeLink::Sender

TChangeLink	See also

Specifies which image list component notifies the change link object of changes.

__property TCustomImageList* Sender = {read=FSender, write=FSender};

Description

Use Sender to access the image list that has changed. The TImageList automatically sets this property when a call to RegisterChanges is made.


TChangeLink events

TChangeLink	Alphabetically

In TChangeLink

OnChange


TChangeLink events

TChangeLink	By object

OnChange


TChangeLink::OnChange

TChangeLink	See also

Occurs when there's a change in any of the images stored in the associated image list.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Use the OnChange event to notify a control when the image list that it’s using changes. Specify any special processing to occur at that time in the OnChange event handler.


TChangeLink methods

TChangeLink	Alphabetically

In TChangeLink

~TChangeLink

Change

TChangeLink

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TChangeLink methods

TChangeLink	By object

~TChangeLink

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TChangeLink


TChangeLink::Change

TChangeLink	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(void);

Description

Use the Change method to trigger the OnChange event handler of the change link object.


TChangeLink::~TChangeLink

TChangeLink	See also

Destroys the change link object and releases the memory allocated to it.

__fastcall virtual ~TChangeLink(void);

Description

Do not call ~TChangeLink directly in an application. Instead, use the delete keyword.


TChangeLink::TChangeLink

TChangeLink

Creates a new TChangeLink object.

__fastcall virtual TChangeLink(void);

Description

Do not call TChangeLink directly. Instead, use the new keyword to create a reference to a TChangeLink object at runtime.


Hierarchy

TObject


 TCheckListBox

Hierarchy	Properties	Methods	Events	See also

TCheckListBox displays a scrollable list with check boxes next to each item.

Unit

checklst

Description

TCheckListBox is similar to TListBox, except that each item has a check box next to it. Users can check or uncheck items in the list.


TCheckListBox properties

TCheckListBox	Alphabetically	Legend

In TCheckListBox

AllowGrayed

Checked

State

Derived from TCustomListBox

BorderStyle

Canvas

Columns

IntegralHeight

ItemHeight

ItemIndex

Items

SelCount

Selected

Sorted

Style

TabWidth

TopIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCheckListBox properties

TCheckListBox	By object	Legend

Align

AllowGrayed

BorderStyle

BoundsRect

Brush

Canvas

Checked

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IntegralHeight

ItemHeight

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

SelCount

Selected

ShowHint

Showing

Sorted

State

Style

TabOrder

TabStop

TabWidth

Tag

TopIndex

Top

VCLComObject

Visible

Width

WindowProc


TCheckListBox::AllowGrayed

TCheckListBox	See also

Determines whether check box can be in a “grayed” state.

__property bool AllowGrayed = {read=FAllowGrayed, write=FAllowGrayed, default=0};

Description

If AllowGrayed is set to true, each item has three possible states: checked, unchecked, and grayed. If AllowGrayed is set to false, each item has only two possible states: checked and unchecked.


TCheckListBox::Checked

TCheckListBox	See also

Indicates which items are checked.

__property bool Checked[int Index] = {read=GetChecked, write=SetChecked};

Description

For each member of the Items array, Checked is true if a check mark appears in the item’s check box. Checked corresponds to the cbChecked state; that is, Checked is true when State = cbChecked and false when State = cbUnchecked or State = cbGrayed.


TCheckListBox::State

TCheckListBox	See also

Indicates which items are checked.

__property Stdctrls::TCheckBoxState State[int Index] = {read=GetState, write=SetState};

Description

For each member of the Items array, State indicates whether its check box is selected (cbChecked), deselected (cbUnchecked), or grayed (cbGrayed). The cbChecked state corresponds to the Boolean property Checked; that is, State = cbChecked when Checked = true.


TCheckListBox events

TCheckListBox	Alphabetically	Legend

In TCheckListBox

OnClickCheck

Derived from TCustomListBox

OnDrawItem

OnMeasureItem

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TCheckListBox events

TCheckListBox	By object	Legend

OnClickCheck

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDrawItem

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMeasureItem

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TCheckListBox::OnClickCheck

TCheckListBox	See also

Occurs when the user selects or deselects an item’s check box.

__property Classes::TNotifyEvent OnClickCheck = {read=FOnClickCheck, write=FOnClickCheck};

Description

Write an OnClickCheck event handler to implement any special processing that should occur when the user checks or unchecks an item.


TCheckListBox methods

TCheckListBox	Alphabetically

In TCheckListBox

~TCheckListBox

TCheckListBox

Derived from TCustomListBox

Clear

ItemAtPos

ItemRect

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCheckListBox methods

TCheckListBox	By object

~TCheckListBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

ItemAtPos

ItemRect

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCheckListBox

Update

UpdateControlState


TCheckListBox::~TCheckListBox

TCheckListBox	See also

Destroys the TCheckListBox instance and frees its memory.

__fastcall virtual ~TCheckListBox(void);

Description

Do not call ~TCheckListBox directly in an application. Instead, use the delete keyword.


TCheckListBox::TCheckListBox

TCheckListBox

Creates a new TCheckListBox object.

__fastcall virtual TCheckListBox(Classes::TComponent* AOwner) : Stdctrls::TCustomListBox(AOwner) { }

__fastcall TCheckListBox(HWND ParentWindow) : Stdctrls::TCustomListBox(ParentWindow) { }

Description

Call TCheckListBox indirectly, using the new keyword, to add a checked listbox to a form at runtime. Checked listboxes added to forms at design time are created automatically.

Pass a single Component as a parameter to provide the TCheckListBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the checked list box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomListBox


TCookieCollection

Hierarchy	Properties	Methods	See also

TCookieCollection is a collection of TCookie objects.

Unit

httpapp

Description

Use TCookieCollection to represent all the Cookie headers of an HTTP response message.  Each Cookie header is represented by a single TCookie object.  A Cookie header includes a named field with an associated value, of the form Name=Value, plus a number of other, standard fields that specify the destination of the cookie, when the cookie is valid, and so on.  Web clients pass Cookie headers on to the destinations specified by the fields of the Cookie header.


TCookieCollection properties

TCookieCollection	Alphabetically	Legend

In TCookieCollection

Items

WebResponse

Derived from TCollection

Count

ItemClass


TCookieCollection properties

TCookieCollection	By object	Legend

Count

ItemClass

Items

WebResponse


TCookieCollection::Items

TCookieCollection	See also

Provides indexed access to the TCookie objects in the collection.

__property TCookie* Items[int Index] = {read=GetCookie, write=SetCookie};

Description

Use Items to access the properties of the TCookie objects maintained by TCookieCollection.


TCookieCollection::WebResponse

TCookieCollection

Indicates the TWebResponse object that uses the cookie collection to represent all of its Cookie headers.

__property TWebResponse* WebResponse = {read=FWebResponse};

Description

Read WebResponse to access the response object that is using the cookie collection.  The response object is a descendant of TWebResponse, either TISAPIResponse, TCGIResponse, or TWinCGIResponse, depending on the type of Web server application.

Use the properties of the response object to obtain information about the other headers in the response message or the content of the response message.  Many applications use this information to determine what field values to specify as Cookie headers.


TCookieCollection methods

TCookieCollection	Alphabetically

In TCookieCollection

~TCookieCollection

Add

TCookieCollection

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCookieCollection methods

TCookieCollection	By object

~TCookieCollection

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCookieCollection


TCookieCollection.Add

TCookieCollection	See also

Creates a new TCookie object and adds it to the end of the Items property array.

HIDESBASE TCookie* __fastcall Add(void);

Description

Call Add to add a new Cookie header to the set of cookie headers sent with the Web response message.  Use Add when adding a Cookie header whose fields will be set at a later time. If the values of the TCookie properties are known at the time of creation, use the SetCookieField method of the Web response object instead.


TCookieCollection::TCookieCollection

TCookieCollection

Creates and initializes a TCookieColleciton item.

__fastcall TCookieCollection(TWebResponse* WebResponse, System::TMetaClass* ItemClass);

Description

Applications should not need to call TCookieCollection directly.  The Web response object that uses the cookie collection to represent its Cookie headers creates the TCookieCollection object from its own constructor.


TCookieCollection::~TCookieCollection

TCookieCollection

~TCookieCollection frees the memory associated with the TCookieCollection object.

__fastcall virtual ~TCookieCollection(void) { }

Description

Do not call ~TCookieCollection directly. Instead, use the delete keyword on the object, which causes ~TCookieCollection to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


 TClientDataSet

Hierarchy	Properties	Methods	Events	See also

TClientDataSet is the class that implements a database-independent dataset component that can be used independently in a single-tiered application, or as a client dataset in the client application portion of a multi-tiered database application.

Unit

dbclient

Description

TClientDataSet encapsulates a database-independent, distributed dataset. A client dataset can be used as a

•	Simple, fully-functional, standalone, flat-file dataset for single-tiered database applications. When used in this manner, an application uses the client dataset to read from and write to a user’s hard disk directly, without accessing a database engine.

•	Client dataset in the client application portion of a multi-tiered database application.

Note:	The two functions described above are not mutually exclusive. A multi-tiered application can be designed to support the option of working with data off-line, using the “briefcase” model. On site, the application uses TClientDataSet to communicate with the application server’s data provider. When a user works off site, the client dataset writes a snapshot of the data to the hard disk.  The application works with this snapshot off sight, with the client dataset acting as a flat-file dataset in a single-tiered application.

The client dataset generally communicates with a data provider through an IProvider dual interface. When used in the one-tiered and briefcase models, the client dataset’s provider interface is automatically generated. When used in a client application as part of a multi-tiered application, the client dataset’s provider is usually a TProvider object that is part of the application server.

Note:	See the EMPEDIT, MSTRDTL, and ACTIVEFM demos for examples of how to use TClientDataSet.


TClientDataSet properties

TClientDataSet	Alphabetically	Legend

In TClientDataSet

CanModify

ChangeCount

Data

DataSource

Delta

FetchOnDemand

Filter

Filtered

FilterOptions

IndexDefs

IndexFieldCount

IndexFieldNames

IndexFields

IndexName

KeyExclusive

KeyFieldCount

KeySize

LogChanges

MasterFields

MasterSource

PacketRecords

Provider

ProviderName

ReadOnly

RecNo

RecordCount

RecordSize

RemoteServer

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

DefaultFields

Designer

EOF

FieldCount

FieldDefs

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TClientDataSet properties

TClientDataSet	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CanModify

ChangeCount

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Data

DataSource

DefaultFields

Delta

Designer

DesignInfo

EOF

FetchOnDemand

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

IndexDefs

IndexFieldCount

IndexFieldNames

IndexFields

IndexName

KeyExclusive

KeyFieldCount

KeySize

LogChanges

MasterFields

MasterSource

Modified

Name

Owner

PacketRecords

Provider

ProviderName

ReadOnly

RecNo

RecordCount

RecordSize

RemoteServer

State

Tag

VCLComObject


TClientDataSet::CanModify

TClientDataSet	See also

Indicates whether an application can insert, edit, or delete data in a client dataset.

__property bool CanModify = {read=GetCanModify, nodefault};

Description

Check the status of CanModify to determine if an application can modify a dataset in any way. If CanModify is true, the dataset can be modified. If CanModify is false, the dataset is read-only.

CanModify is set automatically when an application opens a dataset. If the ReadOnly property of a client dataset component is true, then CanModify is set to false.


TClientDataSet::ChangeCount

TClientDataSet	See also

Indicates the number of changes made to the client dataset.

__property int ChangeCount = {read=GetChangeCount, nodefault};

Description

Check ChangeCount to determine how many modifications are pending for the dataset. When updates are applied, and any differences are reconciled by the client dataset, ChangeCount is reset.


TClientDataSet::Data

TClientDataSet	See also 	Example

Represents data packets from a provider.

__property System::OleVariant Data = {read=GetData, write=SetData};

Description

Use Data to receive and access data packets from a provider. For multi-tiered applications, data packets are typically received from the application server. In one-tiered applications, packets are read from a data file.

The client dataset operates on this local copy of data. For example, the following statement retrieves records from the server and stores them in Data:

ClientDataSet1->Data = ClientDataSet1->Provider->Data;


TClientDataSet::DataSource

TClientDataSet	See also

Specifies the data source for the client dataset.

__property TDataSource* DataSource = {read=GetDataSource};

Description

Use DataSource to examine or set the data source component for a master table used by the dataset.


TClientDataSet::Delta

TClientDataSet	See also

Represents a packet of change log data from the client to a provider.

__property System::OleVariant Delta = {read=GetDelta};

Description

Use Delta to pass a packet of change log data from the client dataset to a provider. Delta contains only information about those records inserted, modified, or deleted through the client. Delta is passed as an argument to the ApplyUpdates and Reconcile methods, which use the information in the change log to update the database.

On return from successful application of updates, Delta is cleared. Depending on the error tolerance allowed by the client dataset through ApplyUpdates, if errors occur, Delta contains one of the following:

•	All log change data, because the maximum number of tolerated errors was encountered and all changes are rolled back.

•	Only those log changes that could not be applied, which indicates that fewer errors occurred than the maximum specified as a tolerance level.


TClientDataSet::FetchOnDemand

TClientDataSet	See also

Indicates whether to fetch data packets from the provider on an as needed basis.

__property bool FetchOnDemand = {read=FFetchOnDemand, write=FFetchOnDemand, default=1};

Description

By default FetchOnDemand is true, meaning that the client dataset fetches additional packets of data as needed (for example, as a user scrolls through data, or conducts a search).

Set FetchOnDemand to false only if your client application contains code that explicitly fetches more data packets as needed using the GetNextPacket method.


TClientDataSet::Filter

TClientDataSet	See also

Specifies the text of the current filter for a dataset.

__property System::AnsiString Filter = {read=FFilterText, write=SetFilterText};

Description

Use Filter to specify a dataset filter. When filtering is applied to a dataset, only those records that meet a filter’s conditions are available to an application. Filter contains the string that describes the filter condition. For example, the following filter condition displays only those records where the State field is 'CA' or 'MA':

State = 'CA' or State = 'MA'

To filter strings based on partial comparisons, use an asterisk as a wildcard. For example:

State = 'M*'

When a filter is set, Blank records do not appear unless explicitly included in the filter.  For example:

State <> 'CA' or State IS NULL

Note:	Applications can set Filter at runtime to change the filtering condition for a dataset at (for example, in response to user input).


TClientDataSet::Filtered

TClientDataSet	See also

Specifies whether or not filtering is active for a dataset.

__property bool Filtered = {read=FFiltered, write=SetFiltered, default=0};

Description

Check Filtered to determine whether or not dataset filtering is in effect. If Filtered is true, then filtering is active. Otherwise Filtered is false. To apply filter conditions specified in the Filter property or the OnFilterRecord event handler, set Filtered to true.

Note:	When filtering is enabled, user edits to a record may mean that the record no longer meets a filter’s test condition. The next time the record is retrieved from the dataset while the filter is in effect, the record may seem to disappear. If that happens, the next record that passes the filter condition becomes the current record.


TClientDataSet::FIlterOptions

TClientDataSet	See also

Specifies whether or not filtering is case insensitive, and whether or not partial comparisons are permitted when filtering records.

enum TFilterOption { foCaseInsensitive, foNoPartialCompare };

typedef Set<TFilterOption, foCaseInsensitive, foNoPartialCompare> TFilterOptions;

__property TFilterOptions FilterOptions = {read=FFilterOptions, write=SetFilterOptions, default=0};

Description

Set FilterOptions to specify whether or not filtering is case insensitive when filtering on string or character fields, and whether or not partial comparisons for matching filter conditions is allowed.

By default, FilterOptions is set to an empty set. For filters based on string fields, set FilterOptions to foCaseInsensitive to catch all variations on a string regardless of capitalization.

To disable partial string matches in the filter expression, include foNoPartialCompare in the filter options.

Note:	To filter strings bases on partial comparisons, use an asterisk as a wildcard. For example:

State = 'M*'


TClientDataSet::IndexDefs

TClientDataSet	See also 	Example

Contains information about the indexes for a client dataset.

__property Db::TIndexDefs* IndexDefs = {read=GetIndexDefs};

Description

Examine IndexDefs for index information. IndexDefs is an array of index items, each of which describes an available index for the dataset. Ordinarily an application accesses or specifies indexes through the IndexFieldNames or IndexFields properties.

Note:	The index items in IndexDefs may not always reflect the current indexes available for a dataset. Before examining IndexDefs, call the IndexDefs->Update method to refresh the item list.


TClientDataSet::IndexFieldCount

TClientDataSet	See also 	Example

Indicates number of fields that make up the current index for the dataset.

__property int IndexFieldCount = {read=GetIndexFieldCount, nodefault};

Description

Check IndexFieldCount to determine how many fields are used by the current index for the dataset.


TClientDataSet::IndexFieldNames

TClientDataSet	See also

Lists the fields to use as an index for a dataset.

__property System::AnsiString IndexFieldNames = {read=GetIndexFieldNames, write=SetIndexFieldNames}

Description

Use IndexFieldNames as an alternative method of specifying the index to use for a dataset. In IndexFieldNames specify the name of each field to use as an index for a dataset. Ordering of field names is significant. Separate names with semicolon.

Tip:	Use IndexFieldNames to create sort orders on the fly at runtime.

Note:	The IndexFieldNames and IndexName properties are mutually exclusive. Setting one clears the other.


TClientDataSet::IndexFields

TClientDataSet	See also 	Example

Specifies the array of fields associated with the current index.

__property Db::TField* IndexFields[int Index] = {read=GetIndexField, write=SetIndexField};

Description

IndexFields provides a zero-based array of field objects, each of which corresponds to a field in the current index. Index is an ordinal value indicating the position of a field in the index. The first field in the index is IndexFields[0], the second is IndexFields[1], and so on.

Note:	Do not set IndexField directly. Instead use the IndexFieldNames property to order datasets on the fly at runtime.


TClientDataSet::IndexName

TClientDataSet	See also 	Example

Identifies an index for the client dataset.

__property System::AnsiString IndexName = {read=GetIndexName, write=SetIndexName};

Description

Use IndexName to specify an alternative index for a dataset.If IndexName is empty, a dataset’s sort order is based on its IndexFieldNames property or on its default ordering in the data packet. Default ordering is determined by the predefined index, DEFAULT_ORDER.

If IndexName contains a valid index name, then that index is used to determine sort order of records.

Note:	IndexFieldNames and IndexName are mutually exclusive. Setting one clears the other.


TClientDataSet::KeyExclusive

TClientDataSet	See also

Specifies the upper and lower boundaries for a range.

__property bool KeyExclusive = {read=GetKeyExclusive, write=SetKeyExclusive, nodefault};

Description

Use KeyExclusive to specify whether or not a range includes or excludes the records that match the specified starting and ending values for a range. By default, KeyExclusive is true, meaning that matching values are included.

To restrict a range to those records that are greater than the specified starting value and less than the specified ending value, set KeyExclusive to false.


TClientDataSet::KeyFieldCount

TClientDataSet	See also

Specifies the number of fields to use when conducting a partial key search on a multi-field key.

__property int KeyFieldCount = {read=GetKeyFieldCount, write=SetKeyFieldCount, nodefault};

Description

Use KeyFieldCount to limit a search based on a multi-field key to a consecutive sub-set of those fields. KeyFieldCount is zero-based. For example, if the primary key for a dataset consists of three-fields, a partial-key search can be conducted using only the first fields in the key by setting KeyFieldCount to 0.

Note:	Searches are only conducted based on consecutive key fields beginning with the first field in the key. For example if a key consists of three fields, an application can set KeyFieldCount to 0 to search on the first field, 1 to search on the first and second fields, or 2 to search on all fields. By default KeyFieldCount is initially set to include all fields in a search.


TClientDataSet::KeySize

TClientDataSet	See also

Indicates the size of the current key used for the dataset.

__property Word KeySize = {read=FKeySize, nodefault};

Description

Examine KeySize to determine the size of the current key used for the dataset. KeySize corresponds to the size of the key fields in the primary index for the dataset.


TClientDataSet::LogChanges

TClientDataSet	See also

Indicates whether to log data changes.

__property bool LogChanges = {read=GetLogChanges, write=SetLogChanges, nodefault};

Description

Use LogChanges to control whether or not changes made to the data in a client dataset are recorded. When LogChanges is true (the default), all changes are recorded and can be returned to the application server. When LogChanges is false, data changes are made in memory, but the changes cannot be passed to the server.

An application that creates a temporary dataset using the CreateDataSet method might set LogChanges to false so it can populate the new dataset with an initial set of values, and then set LogChanges to true to resume recording data changes.

Tip:	When using a client dataset in a one-tiered application where data changes made by the application will never be applied to another dataset, set LogChanges to false to conserve system resources.


TClientDataSet::MasterFields

TClientDataSet	See also

Specifies one or more fields in a master table to link with corresponding fields in this dataset in order to establish a master-detail relationship between them.

__property System::AnsiString MasterFields = {read=GetMasterFields, write=SetMasterFields};

Description

Use MasterFields after setting the MasterSource property to specify the names of one or more fields to use in establishing a detail-master relationship between this dataset and the one specified in MasterSource.

MasterFields is a string containing one or more field names in the master table. Separate field names with semicolons.

Each time the current record in the master table changes, the new values in those fields are used to select corresponding records in this dataset for display.

Note:	At design time, use the Field Link designer to establish the master-detail relationship between two datasets.


TClientDataSet::MasterSource

TClientDataSet	See also

Specifies the name of the data source component for the dataset to use as a master table in establishing a detail-master relationship between this dataset and another one.

__property Db::TDataSource* MasterSource = {read=GetDataSource, write=SetDataSource};

Description

Use MasterSource to specify the name of the data source component whose DataSet property identifies a dataset to use as a master table in establishing a detail-master relationship between this dataset and another one.

Note:	At design time choose an available data source from the MasterSource property’s drop-down list in the Object Inspector.

After setting the MasterSource property, specify which fields to use in the master table by setting the MasterFields property. At runtime each time the current record in the master table changes, the new values in those fields are used to select corresponding records in this dataset for display.

Note:	At design time, use the Field Link designer to establish the master-detail relationship between two datasets.


TClientDataSet::PacketRecords

TClientDataSet	See also

Indicates the number or type of records in a single data packet.

__property int PacketRecords = {read=FPacketRecords, write=FPacketRecords, default=-1};

Description

Use PacketRecords to specify how many records should be contained in a single packet fetched from the application server, or to indicate that the packet returned should contain only metadata from the server.

When a client dataset is instantiated, PacketRecords is automatically set to -1, meaning that a single packet should contain all records in the dataset.

If PacketRecords is greater than zero, then it specifies the exact number of records to return in a packet.

To retrieve the metadata for a dataset, set PacketRecords to 0. When PacketRecords is zero, the application returns all information from the remote database server that define the database’s structure, such as table, column, constraint, and domain definitions.


TClientDataSet::Provider

TClientDataSet	See also 	Example

Points to the IProvider interface used by the client dataset to communicate with a provider object on an application server.

__property Stdvcl::_di_IProvider Provider = {read=GetProvider, write=SetProvider};

Description

Use Provider to read or set the IProvider interface used by the client dataset to communicate with the TProvider object on the application server. Ordinarily an application only queries this property because its value is set automatically based on the ProviderName property when a client dataset registers itself with a remote server object in the client application. If an application server has two or more interfaces that are made available to different remote server objects on the client application, the client can switch among them by changing the value of the Provider property at runtime.

Applications can allow the client dataset to handle all communication with the server application.  However, when greater control is desired, use the Provider property for performing low-level data access.  The IProvider interface includes the following properties and methods.

Property or Method	Description
ApplyUpdates	Sends all updated, inserted, and deleted records from the client dataset to the remote Provider for writing to the database.
Constraints	Instructs the remote Provider whether or not to pass server constraints to the client dataset.
Data	Provides read-only access to the current data packet on the remote Provider.
DataRequest	Generates an OnDataRequest event on the remote Provider.
GetIDsOfNames	Maps a single member and an optional set of argument names to a corresponding set of dispatch identifiers (dispIDs) that can be used on subsequent calls to the Invoke method
GetMetaData	Retrieves a data packet containing only metadata.
GetRecords	Retrieves a specified number of records from the remote Provider.
GetTypeInfo	Retrieves the type information for IProvider.
GetTypeInfoCount	Returns the number of type information interfaces that IProvider provides.
Get_Constraints	Retrieves the value of the Constraints property.
Get_Data	Retrieves the value of the Data property.
Invoke	Provides access properties and methods for OLE automation.
QueryInterface	Returns a reference to a specified interface if it is available.
Reset	Instructs the Provider to supply records starting at the beginning of the remote dataset and determines whether metadata should be included.
SetParams	Passes parameters or range values to the remote dataset.
Set_Constraints	Sets the Constraints property.
_AddRef	Increments the reference count of dependencies on the Provider.
_Release	Decrements the reference count of dependencies on the Provider.
Note:	For more information about specific properties or methods of the IProvider interface, see the corresponding properties or methods of the Provider (or Custom provider) component.


TClientDataSet::ProviderName

TClientDataSet	See also

Specifies the name of the Provider property on the application server that is used by this client dataset on the client application.

__property System::AnsiString ProviderName = {read=FProviderName, write=SetProviderName};

Description

Use ProviderName to specify the provider object with which to communicate on the server. This property is used to request a specific IProvider interface from a remote server object. If the application server contains multiple provider objects, a client application can set ProviderName to any of them once the client’s remote server object establishes an initial connection to the application server.


TClientDataSet::ReadOnly

TClientDataSet	See also

Specifies whether or not a client dataset is read-only for this application.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, default=0};

Description

Use the ReadOnly property to prevent users from updating, inserting, or deleting data in the dataset. By default, ReadOnly is false, meaning users can potentially alter a dataset’s data.

To guarantee that users cannot modify or add data to a dataset, set ReadOnly to true.

When ReadOnly is true, the dataset’s CanModify property is false.

Note:	Even if ReadOnly is false, users may not be able to modify or add data to a dataset.


TClientDataSet::RecNo

TClientDataSet	See also

Indicates the current record in the dataset.

__property int RecNo = {read=GetRecNo, write=SetRecNo, nodefault};

Description

Examine RecNo to determine the record number of the current record in the dataset. Applications might use this property with RecordCount to iterate through all the records in a dataset, though typically record iteration is handled with calls to First, Last, MoveBy, Next, and Prior.


TClientDataSet::RecordCount

TClientDataSet	See also

Indicates the total number of records associated with the dataset.

__property int RecordCount = {read=GetRecordCount, nodefault};

Description

Examine RecordCount to determine the total number of records in the dataset. Applications might use this property with RecNo to iterate through all the records in a dataset, though typically record iteration is handled with calls to First, Last, MoveBy, and Prior.

Note:	If the PacketRecords property is greater than 0, then the value for RecordCount may change as a user scrolls through the data and additional data packets are fetched from the provider.


TClientDataSet::RecordSize

TClientDataSet	See also

Indicates the size of a record in the dataset.

__property Word RecordSize = {read=GetRecordSize, nodefault};

Description

Examine RecordSize to determine the physical size, in bytes, of the buffer C++Builder allocates to hold a record in the dataset. When a dataset is opened, the Open procedure requests record-buffer size information and stores the returned information in RecordSize. C++Builder uses this information internally. Applications seldom, if ever, require this information.


TClientDataSet::RemoteServer

TClientDataSet	See also

Specifies the remote server object in the client application that is used by this client dataset for connection purposes.

__property TCustomRemoteServer* RemoteServer = {read=FRemoteServer, write=SetRemoteServer};

Description

Use RemoteServer to specify the component, usually a MIDAS connection component,  that establishes a connection to the remote server. The remote server is used to obtain an IProvider interface for data exchange in a multi-tiered application. If a client application uses more than remote server object, the application can change which remote server a client dataset uses by changing the value for this property.


TClientDataSet events

TClientDataSet	Alphabetically	Legend

In TClientDataSet

OnReconcileError

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TClientDataSet events

TClientDataSet	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnReconcileError


TClientDataSet::OnReconcileError

TClientDataSet	See also

Occurs when a client dataset needs to reconcile an update to a record that could not be resolved by the provider on the application server.

enum TReconcileAction { raSkip, raAbort, raMerge, raCorrect, raCancel, raRefresh };

enum TUpdateKind { ukModify, ukInsert, ukDelete };

typedef void __fastcall (__closure *TReconcileErrorEvent)(TClientDataSet* DataSet, EReconcileError* E, Db::TUpdateKind UpdateKind, TReconcileAction &Action);

__property TReconcileErrorEvent OnReconcileError = {read=FOnReconcileError, write=FOnReconcileError};

Description

Write an OnReconcileError event handler to respond to error conditions that arise when the Reconcile method cycles through records returned by the application server after it applies updates to a database. Records returned by the server are ones that the server could not apply to the database. Reconcile attempts to handle these records. OnReconcileError is called once for each record returned by the server.

DataSet is the name of the client dataset to which reconciled records are applied.

E is a pointer to a EReconcileError object from which an application can extract an error message and the actual cause of the error condition. An OnReconcileError handler can use this information to determine how to respond to the error condition.

UpdateKind describes the type of update that generated the error. The following table lists the possible values for UpdateKind and what they indicate:

Value	Meaning

ukModify	Editing an existing record caused an error.

ukInsert	Inserting or appending a new record caused an error.

ukDelete	Deleting an existing record raised an error.

Action indicates the action to take when the OnReconcileError handler exits. On entry into the handler, Action is always set to the action taken by the resolution process on the server. If OnReconcileError can handle or correct the error, set Action to raRetry before exiting the error handler. The following table lists the possible values for Action and what they indicate:

Value	Meaning

raSkip	Skips updating the record that raised the error condition, and leaves the unapplied changes in the cache.

raAbort	Aborts the operation without displaying an error message.

raMerge	Merges the updated record with the record on the server.

raCorrect	Reapplies the updated record to the database.

raCancel	Removes changes from the change log.

raRefresh	Updates the current record value and removes the changes from the change log.

Note:	The code in an OnReconcileError handler can examine and apply the OldValue, NewValue, and CurValue properties for each field in the current record, but should not call any methods that make a different record the current one.


TClientDataSet methods

TClientDataSet	Alphabetically

In TClientDataSet

~TClientDataSet

AddIndex

AppendData

ApplyRange

ApplyUpdates

BookmarkValid

CancelRange

CancelUpdates

CloneCursor

CompareBookmarks

ConstraintsDisabled

CreateDataSet

DeleteIndex

DisableConstraints

EditKey

EditRangeEnd

EditRangeStart

EnableConstraints

FindKey

FindNearest

GetCurrentRecord

GetIndexInfo

GetIndexNames

GetNextPacket

GotoCurrent

GotoKey

GotoNearest

LoadFromFile

LoadFromStream

Locate

Lookup

MergeChangeLog

Reconcile

RevertRecord

SaveToFile

SaveToStream

SetAltRecBuffers

SetKey

SetRange

SetRangeEnd

SetRangeStart

TClientDataSet

UndoLastChange

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

Cancel

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Post

Prior

Refresh

Resync

SetFields

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TClientDataSet methods

TClientDataSet	By object

~TClientDataSet

ActiveBuffer

AddIndex

Append

AppendData

AppendRecord

ApplyRange

ApplyUpdates

Assign

BookmarkValid

Cancel

CancelRange

CancelUpdates

CheckBrowseMode

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

CloneCursor

Close

CompareBookmarks

ConstraintsDisabled

ControlsDisabled

CreateDataSet

CursorPosChanged

DefaultHandler

Delete

DeleteIndex

DestroyComponents

Destroying

DisableConstraints

DisableControls

Dispatch

Edit

EditKey

EditRangeEnd

EditRangeStart

EnableConstraints

EnableControls

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindKey

FindLast

FindNearest

FindNext

FindPrior

First

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetIndexNames

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetNextPacket

GetParentComponent

GotoBookmark

GotoCurrent

GotoKey

GotoNearest

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

Last

LoadFromFile

LoadFromStream

Locate

Lookup

MergeChangeLog

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

Post

Prior

Reconcile

Refresh

RemoveComponent

Resync

RevertRecord

SafeCallException

SaveToFile

SaveToStream

SetAltRecBuffers

SetFields

SetKey

SetRange

SetRangeEnd

SetRangeStart

TClientDataSet

Translate

UndoLastChange

UpdateCursorPos

UpdateRecord

UpdateStatus


TClientDataSet::AddIndex

TClientDataSet	See also

Creates a new index for the client dataset.

void __fastcall AddIndex(const System::AnsiString Name, const System::AnsiString Fields, Db::TIndexOptions Options);

Description

Call AddIndex to create a new index for the client dataset. Name is the name of the new index. Fields is a semicolon-delimited list of the fields to include in the index. Options is a potentially restricted set of one or more of the following values:

Value	Meaning

ixDescending	Sort in descending alphanumeric order

ixCaseInsensitive	Ignore case when sorting

Attempting to create an index using options that are not applicable to the table raises an exception.

Note:	Indexes added by AddIndex are not saved with data when using SaveToFile.


TClientDataSet::AppendData

TClientDataSet	See also

Adds a newly fetched packet of records to those already stored in the client dataset.

void __fastcall AppendData(const System::OleVariant &Data, bool HitEOF);

Description

Use AppendData to add a newly fetched packet of records from the server application to the client dataset. Data indicates the packet of records to add. HitEOF indicates whether or not the end of the dataset was encountered by the application server when it fetched the records from the database server.

Unless an application is directly using the Provider property to perform low-level data fetching, there should be no need to call AppendData directly. Instead, most applications should call GetNextPacket to fetch a packet of records and automatically add them to those already available.


TClientDataSet::ApplyRange

TClientDataSet	See also 	Example

Apply a range to the dataset.

void __fastcall ApplyRange(void);

Description

Call ApplyRange to cause a range established with SetRangeStart and SetRangeEnd, or EditRangeStart and EditRangeEnd, to take effect. When a range is in effect, only those records that fall within the range are available to the application for viewing and editing.


TClientDataSet::ApplyUpdates

TClientDataSet	See also

Sends all updated, inserted, and deleted records from the client dataset to the provider on the application server for writing to the database.

int __fastcall ApplyUpdates(int MaxErrors);

Description

Call ApplyUpdates to write all updated, inserted, and deleted records from the client dataset to the provider on the application server. MaxErrors indicates the maximum number of errors that the provider should allow before prematurely stopping the update operation.

If there are pending updates, ApplyUpdates calls the client dataset’s Reconcile method to send the updates to the server and attempts to reconcile any records returned by the server because they generated errors when the server attempted to apply them to the database.

ApplyUpdates returns the number of errors it encountered. Based on this return value and the setting of MaxErrors, successfully applied records are removed from the client dataset’s change log. If MaxErrors is -1, then on error, the update process in aborted, and no records are removed from the change log If MaxErrors is a positive number and more errors occur than permitted by MaxErrors, all updates are aborted. If fewer errors occur than specifiedby MaxErrors all records successfully applied are automatically cleared from the dataset’s change log.


TClientDataSet::BookmarkValid

TClientDataSet	See also

Tests the validity of a specified bookmark.

virtual bool __fastcall BookmarkValid(void * Bookmark);

Description

Determines if a bookmark is valid. Bookmark is the bookmark pointer to test. If the bookmark is valid, BookmarkValid returns true. Otherwise it returns false.


TClientDataSet::CancelRange

TClientDataSet	See also

Removes any ranges currently in effect for the client dataset.

void __fastcall CancelRange(void);

Description

Call CancelRange to remove a range currently applied to a client dataset. Canceling a range reenables access to all records in the dataset.


TClientDataSet::CancelUpdates

TClientDataSet	See also

Clears all pending edits and clears the change log.

void __fastcall CancelUpdates(void);

Description

Call CancelUpdates to clear all pending updates from the Delta property. Delta is a variant maintained by the client dataset to record updates, inserts, and deletes.


TClientDataSet::CloneCursor

TClientDataSet	See also 	Example

Points to the data belonging to another client dataset

void __fastcall CloneCursor(TClientDataSet* Source, bool Reset);

Description

Call CloneCursor to provide a second editable view of the data belonging to another client dataset. Source indicates another client dataset for which to provide a pointer. Reset determines whether or not to clone the source dataset’s current ranges and filters. If Reset is false the current range is applied to the cloned dataset. If Reset is true, the dataset is cloned, but an active range is not applied to the cloned dataset.

The following properties of the specified dataset are cloned:

Property	Property	Property

IndexFieldNames	IndexName	MasterSource

MasterFields	Provider	ProviderName

RemoteServer

CloneCursor closes the dataset, points to the specified client dataset, and opens a second view on it. For example:

After this call, the data for ClientDataSet2 is the same as the data for ClientDataSet1. Edits performed by either client dataset are reflected in the data for ClientDataSet1, and are visible from either dataset.


TClientDataSet::CompareBookmarks

TClientDataSet	See also 	Example

Compare two bookmarks.

virtual int __fastcall CompareBookmarks(void * Bookmark1, void * Bookmark2);

Description

Call CompareBookmarks to determine if two bookmarks are identical or not. Bookmark1 and Bookmark2 are the bookmarks to compare. CompareBookmarks returns -1 if Bookmark1 is less than Bookmark2, 1 if Bookmark1 is greater than Bookmark2, and 0 if the bookmarks are identical or NULL.


TClientDataSet::ConstraintsDisabled

TClientDataSet	See also

Indicates whether or not constraints are enabled for a client dataset.

bool __fastcall ConstraintsDisabled(void);

Description

Call ConstraintsDisabled to determine if constraints are currently disabled for a dataset. If ConstraintsDisabled returns true, constraints are currently disabled. If false, constraints are currently enabled.


TClientDataSet::TClientDataSet

TClientDataSet	See also

Creates an instance of a TClientDataSet component.

__fastcall virtual TClientDataSet(Classes::TComponent* AOwner);

Description

Call TClientDataSet indirectly, using the new keyword, to instantiate a client dataset component at runtime. TClientDataSet clears the Data property and sets up the master links for the dataset.


TClientDataSet::TClientDataSet
TClientDataSet::CreateDataSet

TClientDataSet	See also

Creates a new, empty client dataset.

void __fastcall CreateDataSet(void);

Description

Call CreateDataSet at runtime to create a new, empty client dataset on disk.

If the FieldDefs property contains values, these values are used to create field definitions. Otherwise the Fields property is used. One or both of these properties must contain values in order to create a dataset.

If the IndexDefs property contain values, these values are used to create index definitions for the dataset.


TClientDataSet::DeleteIndex

TClientDataSet	See also

Deletes an index for the client dataset.

void __fastcall DeleteIndex(const System::AnsiString Name);

Description

Call DeleteIndex to remove an index for a client dataset. Name is the name of the index to delete.

Note:	You cannot delete the reserved indexes, DEFAULT_ORDER and CHANGEINDEX.


TClientDataSet::~TClientDataSet

TClientDataSet	See also

Destroys the instance of a client dataset component.

__fastcall virtual ~TClientDataSet(void);

Description

Do not call ~TClientDataSet directly in an application. Usually destruction of datasets is handled automatically. If an application creates its own instances of a dataset, however, it should use the delete keyword.

~TClientDataSet clears the Data property, calls its parent class's destructor, frees the master links for the client dataset, and frees its index definitions list.


TClientDataSet::DisableConstraints

TClientDataSet	See also

Disables application of server constraints on the dataset.

void __fastcall DisableConstraints(void);

Description

Call DisableConstraints to prevent, on a temporary basis, application of server constraints replicated to the dataset. For example, when an application iterates through a dataset, it may improve performance to disable constraints temporarily.

Note:	Calling DisableConstraints increments a reference count. As long as this reference count is greater than zero, constraints are disabled for the dataset. To prevent accidental disabling of constraints, always group a call to DisableConstraints with a call to EnableConstraints.


TClientDataSet::EditKey

TClientDataSet	See also

Enables modification of the search key buffer.

void __fastcall EditKey(void);

Description

Call EditKey to put the client dataset in dsSetKey state while preserving the current contents of the current search key buffer. To determine current search keys, you can use the IndexFields property to iterate over the fields used by the current index.

EditKey is especially useful when performing multiple searches where only one or two field values among many change between each search.


TClientDataSet::EditRangeEnd

TClientDataSet	See also 	Example

Enables changing the ending value for an existing range.

void __fastcall EditRangeEnd(void);

Description

Call EditRangeEnd to change the ending value for an existing range. To specify an end range value, call FieldByName after calling EditRangeEnd. After assigning a new ending value, call ApplyRange to activate the modified range.


TClientDataSet::EditRangeStart

TClientDataSet	See also 	Example

Enables changing the starting value for an existing range.

void __fastcall EditRangeStart(void);

Description

Call EditRangeStart to change the starting value for an existing range. To specify a start range value, call FieldByName after calling EditRangeStart. After assigning a new ending value, call ApplyRange to activate the modified range.


TClientDataSet::EnableConstraints

TClientDataSet	See also

Enables application of server constraints against dataset entries.

void __fastcall EnableConstraints(void);

Description

Call EnableConstraints to turn on application server constraints previously disabled by a call to DisableConstraints.

Note:	Calling EnableConstraints decrements a reference count. When this reference count is zero constraints are enabled for the dataset. To prevent accidental disabling of constraints, always follow a call to DisableConstraints with a matching call to EnableConstraints.


TClientDataSet::FindKey

TClientDataSet	See also 	Example

Searches for a record containing specified field values.

bool __fastcall FindKey(const System::TVarRec * KeyValues, const int KeyValues_Size);

Description

Call FindKey to search for a specific record in a dataset. KeyValues contains an array of field values, called a key. Each value in the key can be a literal, a variable, a null, or NULL. If the number of values passed in KeyValues is less than the number of columns in the index used for the search, the missing values are assumed to be null. KeyValues_Size indicates the index of the last value in the KeyValues array. This is one less than the number of key values.

If a search is successful, FindKey positions the cursor on the matching record and returns true. Otherwise the cursor is not moved, and FindKey returns false.


TClientDataSet::FindNearest

TClientDataSet	See also

Moves the cursor to the record that most closely matches a specified set of key values.

void __fastcall FindNearest(const System::TVarRec * KeyValues, const int KeyValues_Size);

Description

Call FindNearest to move the cursor to a specific record in a dataset or to the first record in the dataset that is greater than the values specified in the KeyValues parameter. KeyValues contains an array of field values, called a key. If the number of values passed in KeyValues is less than the number of columns in the index used for the search, the missing values are assumed to be null. KeyValues_Size specifies the index of the last value in the KeyValues array. This is one less than the number of key values.

Note:	FindNearest works only with string data types.

FindNearest positions the cursor either on a record that exactly matches the search criteria, or on the first record whose values are greater than those specified in the search criteria. The current setting of KeyExclusive also affects this behavior.


TClientDataSet::GetCurrentRecord

TClientDataSet	See also

Retrieves the current record into a buffer.

virtual bool __fastcall GetCurrentRecord(char * Buffer);

Description

Most applications should not need to call GetCurrentRecord. TClientDataSet automatically allocates a buffer for the active record.

Call GetCurrentRecord to copy the current record into a buffer allocated by the application. Buffer must be at least as big as the record size indicated by the RecordSize property.


TClientDataSet::GetIndexInfo

TClientDataSet	See also

Retrieves information about a dataset’s current index.

void __fastcall GetIndexInfo(void);

Description

Call GetIndexInfo to populate a dataset’s internal index fields with information about the current index, including its field count, map, and key size.


TClientDataSet::GetIndexNames

TClientDataSet	See also

Retrieves a list of available indexes for a client dataset.

void __fastcall GetIndexNames(Classes::TStrings* List);

Description

Call GetIndexNames to retrieve a list of all available indexes for a client dataset. List is a string list object, created and maintained by the application, into which to retrieve the index names.

Note:	Two indexes are automatically generated for all client datasets:

•	DEFAULT_ORDER, which describes the order of data when it is put into the data packet.

•	CHANGEINDEX, which orders the data as it would if it were a delta assigned to another dataset.


TClientDataSet::GetNextPacket

TClientDataSet	See also

Retrieves the next block of records from the application server.

int __fastcall GetNextPacket(void);

Description

Call GetNextPacket to retrieve the next sequential block of records from the application server. To specify the maximum number of records to return in a packet, set the PacketRecords property before calling GetNextPacket. A packet is appended to those records already stored in the Data property.

GetNextPacket returns the number of records added to Data. If the return value is 0, the client application has already received all available records from the application server.


TClientDataSet::GotoCurrent

TClientDataSet	See also 	Example

Sets the current record in this dataset the same as the current record in another, cloned dataset.

void __fastcall GotoCurrent(TClientDataSet* DataSet);

Description

Call GotoCurrent to position the cursor on the same record that is current in the specified dataset. DataSet is the cloned dataset whose cursor position in to be matched in this dataset.

GotoCurrent is only useful for synchronizing two client datasets that use separate data sources to view and edit the same data.


TClientDataSet::GotoKey

TClientDataSet	See also

Moves the cursor to a record specified by the current key.

bool __fastcall GotoKey(void);

Description

Use GotoKey to move to a record specified by key values assigned with previous calls to SetKey or EditKey and actual search values indicated in the search key buffer.

If GotoKey finds a matching record, it positions the cursor on the record and returns true. Otherwise the current cursor position remains unchanged, and GotoKey returns false.


TClientDataSet::GotoNearest

TClientDataSet	See also

Moves the cursor to the record that most closely matches the current key.

void __fastcall GotoNearest(void);

Description

Call GotoNearest to position the cursor on the record that is either the exact record specified by the current key values in the key buffer, or on the first record whose values exceed those specified.

Note:	KeyExclusive determines which records are considered part of a search range.

Before calling GotoNearest, an application must specify key values by calling SetKey or EditKey to put the dataset is dsSetKey state, and then use FieldByName to populate the buffer with search values.


TClientDataSet::LoadFromFile

TClientDataSet	See also

Loads a client dataset’s data from a file.

void __fastcall LoadFromFile(const System::AnsiString FileName);

Description

Call LoadFromFile to populate the Data property of the client dataset with data stored in an external file. FileName is the name of the file containing the data to load.

To load data from a file at design time, right-click on the client dataset and choose Load from File.

Note:	FileName must contain data saved to a file by a previous call to this or another client dataset’s SaveToFile method.


TClientDataSet::LoadFromStream

TClientDataSet	See also

Loads a client dataset’s data from a stream.

void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Call LoadFromStream to populate the Data property of the client dataset with data from a stream. Stream is the name of the stream from which to read data.

Note:	Stream must contain data in a client dataset’s internal block format (for example, data written to a stream by another client dataset using the SaveToStream method.


TClientDataSet::Locate

TClientDataSet	See also

Searches the dataset for a specified record and makes that record the current record.

enum TLocateOption { loCaseInsensitive, loPartialKey };

typedef Set<TLocateOption, loCaseInsensitive, loPartialKey> TLocateOptions;

virtual bool __fastcall Locate(const System::AnsiString KeyFields, const System::Variant &KeyValues, Db::TLocateOptions Options);

Description

Call Locate to search a dataset for a specific record and position the cursor on it. KeyFields is a string containing a semicolon-delimited list of field names on which to search.

KeyValues is a variant containing the values to match in the key fields. To specify multiple search values, pass KeyValues as a variant array as an argument. For example:

TLocateOptions Opts;

Opts.Clear();

Opts << loPartialKey;

Variant locvalues[2];

locvalues[0] = Variant("Sight Diver");

locvalues[1] = Variant("P");

CustTable->Locate("Company;Contact", VarArrayOf(locvalues, 1), Opts);

Options is a set that optionally specifies additional search latitude when searching on string fields. If Options contains the loCaseInsensitive setting, then Locate ignores case when matching fields. If Options contains the loPartialKey setting, then Locate finds the first record that fulfills at least some initial part of the KeyValues criteria for record matching. If Options is an empty set, or if the KeyFields are not string fields, Options is ignored.

Locate returns true if it finds a matching record, and makes that record the current one. Otherwise Locate returns false.


TClientDataSet::Lookup

TClientDataSet	See also

Retrieves field values from a record that matches specified search values.

virtual System::Variant __fastcall Lookup(const System::AnsiString KeyFields, const System::Variant &KeyValues, const System::AnsiString ResultFields);

Description

Call Lookup to retrieve values for specified fields from a record that matches search criteria. KeyFields is a string containing a semicolon-delimited list of field names on which to search.

KeyValues is a variant containing the values to match in the key fields. To specify multiple search values, pass KeyValues as a variant array as an argument. For example:

Variant locvalues[2];

locvalues[0] = Variant("Sight Diver");

locvalues[1] = Variant("Kato Paphos");

Variant LookupResults = CustTable->Lookup("Company;City", VarArrayOf(locvalues, 1), "Company;Addr1;Addr2;State;Zip");

ResultFields is a string containing a semicolon-delimited list of field names whose values should be returned from the matching record.

Lookup returns a variant array containing the values from the fields specified in ResultFields.


TClientDataSet::MergeChangeLog

TClientDataSet	See also

Merges any data changes in the change log into the client dataset, overwriting existing values.

void __fastcall MergeChangeLog(void);

Description

Call MergeChangeLog to merge changes in the change log into the actual data for the dataset, effectively creating a new data baseline. Existing values for which changes exist are overwritten.

Note:	Ordinarily, applications need not call this method. It is called automatically by ApplyUpdates as part of the updating process.


TClientDataSet::Reconcile

TClientDataSet	See also

Clears successfully updated records from the client dataset’s cache of changes.

bool __fastcall Reconcile(const System::OleVariant &Results);

Description

Reconcile is called by the ApplyUpdates function to handle error conditions that occur during the update process. Reconcile is called after changes are applied to the dataset managed by a provider from the changes in a client dataset’s Delta property. (In a multi-tiered application, the provider resides on the application server.)

Results is a variant, declared by an application, that contains error information and record information for each record that could not be applied by the provider.

If all updates are applied successfully, Results is null, and all records are automatically cleared from the dataset’s change log by a call to MergeChangeLog.

If errors occurs during the update process, Results contains error records, and records in the change log may not be removed, depending on the setting of the MaxErrors parameter in ApplyUpdates. If MaxErrors is -1, then on error, the update process in aborted, and no records are removed from the change log, and the contents of Results matches the contents of Delta. If MaxErrors is a positive number and more errors occur than permitted by MaxErrors, all updates are aborted, and Results contains only those records that generated an error. If fewer errors occur than specified by MaxErrors, Results again contains error records, but all records successfully applied are automatically cleared from the dataset’s change log.

Reconcile returns a Boolean value indicating whether or not reconciling is successful. If true, Reconcile succeeded without error. If false, one or more errors could not be reconciled.


TClientDataSet::RevertRecord

TClientDataSet	See also

Undoes edits to the current record.

void __fastcall RevertRecord(void);

Description

Call RevertRecord to remove any modifications made to the current record. RevertRecord can only remove modifications to records that have not been applied to the database by the application server.

Note:	To undo the last edit made to a record, call UndoLastChange. To cancel all pending modifications, call CancelUpdates.


TClientDataSet::SaveToFile

TClientDataSet	See also

Saves a client dataset’s data to an external file.

void __fastcall SaveToFile(const System::AnsiString FileName);

Description

Call SaveToFile to write a client dataset’s data to an external file for later use by this or other client datasets. FileName is the name of the external file to use. If the file already exists, its current contents are overwritten.


TClientDataSet::SaveToStream

TClientDataSet	See also

Saves a client dataset’s data to a stream.

void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Call SaveToStream to write a client dataset’s data to a stream for immediate use by other datasets. Stream is the name of an existing stream to write to.


TClientDataSet::SetAltRecBuffers

TClientDataSet	See also

Sets record buffers when accessing field values.

void __fastcall SetAltRecBuffers(char * Old, char * New, char * Cur);

Description

Applications do not normally need to call this method. SetAltRecBuffers sets pointers to records buffers that are used when accessing the OldValue, NewValue, and CurValue properties of a field component belonging to the client dataset. These value are accessed only during update processing.


TClientDataSet::SetKey

TClientDataSet	See also

Enables setting of keys and ranges for a dataset prior to a search.

void __fastcall SetKey(void);

Description

Call SetKey to put the dataset into dsSetKey state and clear the current contents of the search key buffer. Use FieldByName to supply the buffer then with a new set of values prior to conducting a search.

Note:	To modify an existing key or range, call EditKey.


TClientDataSet::SetRange

TClientDataSet	See also 	Example

Sets the starting and ending values of a range, and applies it.

void __fastcall SetRange(const System::TVarRec * StartValues, const int StartValues_Size, const System::TVarRec * EndValues, const int EndValues_Size);

Description

Call SetRange to specify a range and apply it to the dataset.

StartValues indicates the field values that designate the first record in the range. StartValues_Size is the index of the last value in the StartValues array.

EndValues indicates the field values that designate the last record in the range. EndValues_Size is the index of the last value in the EndValues array.

SetRange combines the functionality of SetRangeStart, SetRangeEnd, and ApplyRange in a single procedure call. SetRange performs the following functions:

1	Puts the dataset into dsSetKey state.

2	Erases any previously specified starting range values and ending range values.

3	Sets the start and end range values.

4	Applies the range to the dataset.

If either StartValues or EndValues has fewer elements than the number of fields in the current index, then the remaining entries are set to NULL.


TClientDataSet::SetRangeEnd

TClientDataSet	See also 	Example

Indicates that subsequent assignments to field values specify the end of the range of rows to include in the dataset.

void __fastcall SetRangeEnd(void);

Description

Call SetRangeEnd to put the dataset into dsSetKey state, erase any previous end range values, and set them to NULL. Subsequent field assignments made with FieldByName specify the actual set of ending values for a range.

After assigning end-range values, call ApplyRange to activate the modified range.


TClientDataSet::SetRangeStart

TClientDataSet	See also 	Example

Indicates that subsequent assignments to field values specify the start of the range of rows to include in the dataset.

void __fastcall SetRangeStart(void);

Description

Call SetRangeStart to put the dataset into dsSetKey state, erase any previous start range values, and set them to NULL. Subsequent field assignments to FieldByName specify the actual set of starting values for a range.

After assigning start-range values, call ApplyRange to activate the modified range.


TClientDataSet::UndoLastChange

TClientDataSet	See also

Undoes the last edit, insert, or delete operation to a record in the client dataset.

bool __fastcall UndoLastChange(bool FollowChange);

Description

Call UndoLastChange to undo the last edit, insert, or delete operation to a record in the client dataset. FollowChange indicates whether or not to reposition the cursor on the restored record. If FollowChange is true, the cursor is positioned on the restored record. If FollowChange is false, the cursor remains on current record.


TClientDataSet::UpdateStatus

TClientDataSet	See also 	Example

Reports the current update status for the current record in the dataset.

enum TUpdateStatus { usUnmodified, usModified, usInserted, usDeleted };

Db::TUpdateStatus __fastcall UpdateStatus(void);

Description

Call UpdateStatus to determine the update status for the current record in the client dataset. Update status can change frequently as records are edited, inserted, or deleted. UpdateStatus offers a convenient method for applications to assess the current status before undertaking or completing operations that depend on the update status of the current record.

The return value of the UpdateStatus method is one of the following:

Value	Description
usUnmodified	Record contents have not been changed
usModified	Record contents have been changed
usInserted	Record has been inserted
usDeleted	Record has been deleted
Note:	To determine whether or not there are updates pending for an entire dataset, check the ChangeCount property.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet


 TClientSocket

Hierarchy	Properties	Methods	Events	See also

TClientSocket manages socket connections for a TCP/IP client.

Unit

scktcomp

Description

Add a TClientSocket object to a form or data module to turn an application into a TCP/IP client. TClientSocket specifies a desired connection to a TCP/IP server, manages the connection when it is open, and terminates the connection when the application is through.

Note:	See the CHAT demo for an example of how to use TClientSocket.


TClientSocket properties

TClientSocket	Alphabetically	Legend

In TClientSocket

ClientType

Socket

Derived from TAbstractSocket

Active

Address

Host

Port

Service

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TClientSocket properties

TClientSocket	By object	Legend

Active

Address

ClientType

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Host

Name

Owner

Port

Service

Socket

Tag

VCLComObject


TClientSocket::ClientType

TClientSocket	See also

Specifies whether the client socket reads and writes information asynchronously over the socket connection.

enum TClientType { ctNonBlocking, ctBlocking };

__property TClientType ClientType = {read=GetClientType, write=SetClientType, nodefault};

Description

Set ClientType to ctNonBlocking to enable the client socket to respond to asynchronous reading and writing events. When ClientType is ctNonBlocking, execution is not blocked by reading and writing over the socket connection. OnRead or OnWrite events occur when the socket needs to read or write over the connection.

Set ClientType to ctBlocking to force all reading and writing to occur synchronously. It is a good idea to include the client socket object in a thread if the ClientType is ctBlocking, so that I/O does not block all execution within the client application.

When ClientType is ctBlocking, use a TWinSocketStream object for reading and writing. TWinSocketStream prevents the application from hanging indefinitely if a problem occurs while reading or writing. It also can wait for the socket connection to indicate its readiness for reading.

Use a non-blocking socket when the socket needs to synchronize reading and writing with server sockets.


TClientSocket::Socket

TClientSocket 	Example

Describes the client endpoint of the Windows client socket connection.

__property TClientWinSocket* Socket = {read=FClientSocket};

Description

Use Socket to

•	Determine the address and port of both the client and server sockets that are bound to the connection.

•	Read or write information through the socket connection.

•	Determine what server notifications the client will respond to.

•	Obtain the Windows socket handle for making Windows socket API calls.


TClientSocket events

TClientSocket	Alphabetically	Legend

Derived from TCustomSocket

OnConnect

OnConnecting

OnDisconnect

OnError

OnLookup

OnRead

OnWrite


TClientSocket events

TClientSocket	By object	Legend

OnConnect

OnConnecting

OnDisconnect

OnError

OnLookup

OnRead

OnWrite


TClientSocket methods

TClientSocket	Alphabetically

In TClientSocket

~TClientSocket

TClientSocket

Derived from TAbstractSocket

Close

Open

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TClientSocket methods

TClientSocket	By object

~TClientSocket

AfterConstruction

Assign

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

SafeCallException

TClientSocket


TClientSocket::TClientSocket

TClientSocket	See also

Creates an instance of TClientSocket.

__fastcall virtual TClientSocket(Classes::TComponent* AOwner);

Description

Call TClientSocket indirectly, using the new keyword, to create and initialize a client socket component at runtime. TClientSocket objects placed at design time are created automatically.

After calling the parent object’s constructor, TClientSocket

•	Allocates the TClientWinSocket object that describes the client endpoint of the Windows socket connection.

•	Initializes the event and error dispatchers for the client socket.


TClientSocket::~TClientSocket

TClientSocket	See also

Destroys an instance of TClientSocket.

__fastcall virtual ~TClientSocket(void);

Description

Do not call ~TClientSocket directly in an application. Instead, use the delete keyword.

~TClientSocket frees the TClientWinSocket object that describes the client endpoint of the Windows socket connection.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TAbstractSocket

TCustomSocket


TClipboard

Hierarchy	Properties	Methods	See also

TClipboard encapsulates the Windows Clipboard.

Unit

clipbrd

Description

The Windows Clipboard represents the container for any text or graphics that are cut, copied or pasted from or to an application. TClipboard is a C++Builder object wrapper for the Windows Clipboard.

The Clipbrd header file (Clipbrd.hpp) automatically instantiates a TClipboard. Use a Clipboard object in this manner rather than by instantiating it by calling the Create constructor. The Clipboard function safeguards accidental deletion of the Clipboard.

The properties of the Clipboard provide information about the formats that the Clipboard is “registered” to handle.

The methods of the Clipboard

•	Get and retrieve data according to the appropriate format.

•	Handle reference counting, and opening and closing the Clipboard

•	Manage and manipulate formats for objects in the Clipboard.


TClipboard properties

TClipboard	Alphabetically	Legend

In TClipboard

AsText

FormatCount

Formats


TClipboard properties

TClipboard	By object	Legend

AsText

FormatCount

Formats


TClipboard::AsText

TClipboard	See also 	Example

Represents the current contents of the Clipboard as a string.

__property System::AnsiString AsText = {read=GetAsText, write=SetAsText};

Description

Use the AsText property to place text in and retrieve text from the Clipboard. AsText copies a string on the Clipboard. Assign a string as the value of AsText.

The string value of the AsText property is limited to 255 characters. To set and retrieve more than 255 characters, use the SetTextBuf and GetTextBuf Clipboard methods.

The Clipboard must contain a string or an exception occurs. To determine if the Clipboard contains a string type, use the HasFormat method.


TClipboard::FormatCount

TClipboard	See also 	Example

Specifies the number of formats in the Formats array property.

__property int FormatCount = {read=GetFormatCount, nodefault};

Description

Use FormatCount to find the number of different format types used to encode the information currently stored in the Clipboard. FormatCount is read-only.

To find out if a particular format is available on the Clipboard, use the HasFormat method.

Before writing information to the Clipboard in a particular format, the format must be registered. To register a new format, use the RegisterClipboardFormat method of TPicture.


TClipboard::Formats

TClipboard	See also 	Example

Provides indexed access to all the formats the Clipboard contains.

__property Word Formats[int Index] = {read=GetFormats};

Description

Use Formats to determine what formats are used to encode the information currently on the Clipboard.  Each format can be accessed by its position in the array using the Index parameter. When reading information from the Clipboard, use the Formats array to choose the best possible encoding for information that can be encoded in several ways.

Usually when an application copies or cuts something to the Clipboard, it places it there in multiple formats.

An application can place items of a particular format on the Clipboard and retrieve items with a particular format from the Clipboard if the format is in the Formats array. To find out if a particular format is available on the Clipboard use the HasFormat method.


TClipboard methods

TClipboard	Alphabetically

In TClipboard

~TClipboard

Assign

Clear

Close

GetAsHandle

GetComponent

GetTextBuf

HasFormat

Open

SetAsHandle

SetComponent

SetTextBuf

TClipboard

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TClipboard methods

TClipboard	By object

~TClipboard

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

Close

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetAsHandle

GetComponent

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetTextBuf

HasFormat

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Open

SafeCallException

SetAsHandle

SetComponent

SetTextBuf

TClipboard


TClipboard::Assign

TClipboard	See also	Example

Retrieves an object from the Clipboard or copies an object to the Clipboard.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign place pictures in and retrieve pictures from the Clipboard.

The object specified by the Source paramter is the object being copied. For example, the following code copies the bitmap from a bitmap object named Bitmap1 to the Clipboard:

To retrieve an object from the Clipboard, Assign (the object that is in) the Clipboard to the new object, that is, to the object that is calling its own Assign method. For example, if a bitmap is on the Clipboard, the following code copies it to a bitmap object named Bitmap1:

The Formats property lists the types of formats used to copy an object to the Clipboard. Graphic objects such as bitmaps and metafiles have their own corresponding formats.  Use the HasFormat method to determine whether the information on the Clipboard uses a format compatible with the object it is assigned to.


TClipboard::Clear

TClipboard

Deletes the contents of the Clipboard.

void __fastcall Clear(void);

Description

Call Clear to empty the Clipboard. Clear is called automatically each time data is added to the Clipboard (cut and copy operations).


TClipboard::Close

TClipboard	See also 	Example

Closes the Clipboard if it is open.

void __fastcall Close(void);

Description

Call Close when you are finished adding items to the Clipboard.

The Clipboard can be opened with a call to Open multiple times before being closed. Open and Close maintain a count of the number of times the Clipboard has been opened.  It will not actually close the Clipboard until it has been closed the same number of times it has been opened.


TClipboard::GetAsHandle

TClipboard	See also 	Example

Returns the data from the Clipboard in a raw Windows handled for the specified format.

int __fastcall GetAsHandle(Word Format);

Description

Use GetAsHandle to add other formats to the Clipboard using Windows handles. The handle is not owned by the application and the data should be copied.

Note:	The handle returned by GetAsHandle is only valid as long as the Clipboard is open. As soon as the Clipboard is closed, the handle is deallocated by Windows and is no longer accessible. If you need data associated with the handle for a long period of time, you should copy the data to another handle.

See the Windows API Help file for information about the available formats.


TClipboard::GetComponent

TClipboard	See also 	Example

Pastes a component from the Clipboard according to the values of the Owner and Parent parameters.

Classes::TComponent* __fastcall GetComponent(Classes::TComponent* Owner, Classes::TComponent* Parent);

Description

Use GetComponent to retrieve a component object to the Clipboard, specifying Owner as the component that becomes the owner of the retrieved componentusually this is a form. With Parent, specify the component that becomes the parent of the component. Both Owner and Parent can be NULL.

Before a class can be read in from the Clipboard, it must first be registered with the Classes header file (Classes.hpp) by calling RegisterClasses. If you attempt to read in a class that is not registered, you will receive an EClassNotFound exception.


TClipboard::GetTextBuf

TClipboard	See also

Retrieves text from the Clipboard and copies it to a buffer.

int __fastcall GetTextBuf(char * Buffer, int BufSize);

Description

Use GetTextBuf to retrieve text from the Clipboard and copy it into the buffer pointed to by Buffer. GetTextBuf copies up to the number of characters given by BufSize, and returns the number of characters copied.

The resulting text in Buffer is a null-terminated string.


TClipboard::HasFormat

TClipboard 	Example

Indicates if the Clipboard object contains a particular format.

bool __fastcall HasFormat(Word Format);

Description

Use HasFormat to find out if the information on the Clipboard is encoded using a specific format. If HasFormat is true, the format is present; if false, the format is absent. The Clipboard object keeps a list of available formats in the Formats array property.

Some of the possible values of the Format parameter follow. Many more Clipboard formats are provided by Windows or other Windows applications. Custom formats can be registered also. All are supported by HasFormat.

Value	Meaning

CF_TEXT	Text with each line ending with a CR-LF combination. A null character identifies the end of the text.

CF_BITMAP	A Windows bitmap graphic.

CF_METAFILEPICT	A Windows metafile graphic.

CF_PICTURE	An object of type TPicture.

CF_OBJECT	Any persistent object.


TClipboard::Open

TClipboard	See also 	Example

Opens the Clipboard, preventing other applications from changing its contents until the Clipboard is closed.

void __fastcall Open(void);

Description

When adding a single item to the Clipboard, an application doesn't have to call Open->To to add a series of items to the Clipboard, however, calling Open prevents the contents from being overwritten with each addition.

To add multiple items, you should use the Open method to prevent the contents from being overwritten or being changed by another application.

When an application has added all items to the Clipboard, it should call the Close method.


TClipboard::SetAsHandle

TClipboard 	See also	Example

Places the data in the given format as a Windows handle.

void __fastcall SetAsHandle(Word Format, int Value);

Description

Use SetAsHandle to add other formats to the Clipboard using Windows handles. SetAsHandle places the handle on the Clipboard in the given format.

Once an application gives the handle to the Clipboard, it should not delete the handle Value. Instead, the Clipboard will delete the handle.

Note:	See the Windows API Help file for information about the available formats for Format parameter.


TClipboard::SetComponent

TClipboard	See also 	Example

Copies a component to the Clipboard.

void __fastcall SetComponent(Classes::TComponent* Component);

Description

Use SetComponent to add or retrieve a component object to the Clipboard. Specify the component you want copied as the value of the Component parameter.


TClipboard::SetTextBuf

TClipboard	See also

Places the control's text to the text in the buffer pointed to by Buffer.

void __fastcall SetTextBuf(char * Buffer);

Description

Use SetTextBuf to copy text from a control into a buffer. Buffer must point to a null-terminated string.


TClipboard::TClipboard

TClipboard

Creates a new TClipboard object.

__fastcall virtual TClipboard(void) { }

Description

Do not call the TClipboard object directly. Instead, use the new keyword to create a reference to TClipboard at runtime.


TClipboard::~TClipboard

TClipboard

Frees the memory associated with the TClipboard object.

__fastcall virtual ~TClipboard(void) { }

Description

~TClipboard frees the memory associated with the TClipboard object. Do not call ~TClipboard directly. Instead, use the delete keyword.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TClientWinSocket

Hierarchy	Properties	Methods	Events	See also

TClientWinSocket describes the client endpoint of a Windows socket connection.

Unit

scktcomp

Description

Client socket components use TClientWinSocket to manage the Windows socket API calls for a TCP/IP client application. TClientWinSocket differs from its immediate ancestor TCustomWinSocket only in that it introduces a ClientType property to distinguish blocking from non-blocking client sockets.


TClientWinSocket properties

TClientWinSocket	Alphabetically	Legend

In TClientWinSocket

ClientType

Derived from TCustomWinSocket

Addr

ASyncStyles

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle


TClientWinSocket properties

TClientWinSocket	By object	Legend

Addr

ASyncStyles

ClientType

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle


TClientWinSocket::ClientType

TClientWinSocket	See also

Specifies whether the client Windows socket reads and writes information asynchronously over the socket connection.

enum TClientType { ctNonBlocking, ctBlocking };

__property TClientType ClientType = {read=FClientType, write=SetClientType, nodefault};

Description

Client socket components set ClientType to reflect their own ClientType property. When ClientType is ctNonBlocking, the client Windows socket responds to asynchronous reading and writing events, and execution is not blocked by reading and writing over the connection. OnSocketEvent events occur when the socket needs to read or write over the connection.

When ClientType is ctBlocking, all reading and writing occur synchronously. It is a good idea to perform all reading and writing in a separate thread if ClientType is ctBlocking. Reading and writing in a separate thread ensures that these operations do not block all execution within the client application.

When ClientType is ctBlocking, use a TWinSocketStream object for reading and writing. TWinSocketStream times out so that the application does not hang when a problem occurs while reading or writing. TWinSocketStream also provides a method to wait, before reading, until the socket connection is ready to send information.

Use a non-blocking socket when the socket needs to synchronize reading and writing with server sockets.


TClientWinSocket events

TClientWinSocket	Alphabetically

Derived from TCustomWinSocket

OnErrorEvent

OnSocketEvent


TClientWinSocket events

TClientWinSocket	By object

OnErrorEvent

OnSocketEvent


TClientWinSocket methods

TClientWinSocket	Alphabetically

In TClientWinSocket

~TClientWinSocket

Connect

TClientWinSocket

Derived from TCustomWinSocket

Accept

Close

Disconnect

Listen

Lock

LookupName

LookupService

Open

Read

ReceiveBuf

ReceiveLength

ReceiveText

SendBuf

SendStream

SendStreamThenDrop

SendText

Unlock

Write

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TClientWinSocket methods

TClientWinSocket	By object

~TClientWinSocket

Accept

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

Connect

DefaultHandler

Disconnect

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

Listen

Lock

LookupName

LookupService

MethodAddress

MethodName

NewInstance

Open

Read

ReceiveBuf

ReceiveLength

ReceiveText

SafeCallException

SendBuf

SendStream

SendStreamThenDrop

SendText

TClientWinSocket

Unlock

Write


TClientWinSocket::Connect

TClientWinSocket	See also

Responds to connection notifications.

virtual void __fastcall Connect(int Socket);

Description

Applications can not call this protected method. Connect is called in response to notifications that the client socket has successfully completed a connection to a server socket. The Socket parameter is the Windows socket handle for the socket that receives the notification.

Connect generates an OnSocketEvent event with the SocketEvent parameter set to seConnect. Socket components assign an OnSocketEvent event handler that responds to this event by generating an OnConnect event on the socket component.

Note:	Connect is only called if the ASyncStyles property includes asConnect.


TClientWinSocket::TClientWinSocket

TClientWinSocket

Creates a new TClientWinSocket object.

__fastcall TClientWinSocket(int ASocket) : Scktcomp::TCustomWinSocket(ASocket) { }

Description

Do not create TClientWinSocket objects. They are created automatically by the client sockets that use them. The ASocket parameter specifies the client socket that uses this TClientWinSocket object form managing its socket connection.


TClientWinSocket::~TClientWinSocket

TClientWinSocket

~TClientWinSocket frees the memory associated with the TClientWinSocket object.

__fastcall virtual ~TClientWinSocket(void) { }

Description

Do not call ~TClientWinSocket directly. Instead, use the delete keyword on the object, which causes ~TClientWinSocket to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TCustomWinSocket


TComponent

Hierarchy	Properties	Methods	See also

TComponent is the common ancestor of all component objects in C++Builder.

Unit

classes

Description

TComponent encapsulates the fundamental behavior common to all components in C++Builder by introducing methods and properties that provide:

•	The ability to appear on Component palette and be manipulated in the form designer.

•	The ability to own and manage other components.

•	Enhanced streaming and filing capabilities.

•	The ability for components to be used as wrappers for ActiveX controls and other objects that implement interfaces.

Do not create instances of TComponent. Use TComponent as a base class when declaring non-visual components that can appear on the component palette and be used in the form designer. Properties and methods of TComponent provide basic behavior that descendent classes inherit as well as behavior that components can override to customize their behavior.

To create visual components, use TControl or its descendants as a base. To create visual windowed controls use TWinControl or its descendants as a base.


TComponent properties

TComponent	Alphabetically	Legend

In TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TComponent properties

TComponent	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TComponent::ComObject

TComponent	See also

Specifies the interface reference implemented by components that support COM.

__property _di_IUnknown ComObject = {read=GetComObject};

Description

Use ComObject to assign the interface implemented by a component to an interface reference. This property is used by VCL components that support COM interfaces. If the component is not a wrapper for a COM component, ComObject throws an EComponentError exception.


TComponent::ComponentCount

TComponent	See also 	Example

Indicates the number of components owned by the component as listed in the Components array property list.

__property int ComponentCount = {read=GetComponentCount, nodefault};

Description

Use ComponentCount to find or verify the number of components owned by a component, or when iterating through the Components list to perform some action on all owned components. ComponentCount is used internally in C++Builder for such iterative procedures.

Note:	The ComponentCount of a component contains the same number of items as in the Components list for that component, and is always 1 more than the highest Components index, because the first Components index is always 0.


TComponent::ComponentIndex

TComponent	See also	Example

Indicates the position of the component in its owner's Components array property list.

__property int ComponentIndex = {read=GetComponentIndex, write=SetComponentIndex, nodefault};

Description

Use ComponentIndex when iterating through the Components list to perform some action on owned components. For convenience it can be used in conjunction with ComponentCount. ComponentIndex is used internally in C++Builder for iterative assignment procedures.

Note:	The first component in the list has a ComponentIndex value of 0, the second has a value of 1, and so on. Therefore, when using ComponentIndex with ComponentCount, note that ComponentCount is always 1 more than the highest Components index.


TComponent::Components

TComponent	See also 	Example

Provides indexed access to all components owned by the component.

__property TComponent* Components[int Index] = {read=GetComponent};

Description

Use Components to access any of these owned components, such as the controls owned by a form. The Components property is most useful when needing to refer to owned components by number rather than name. It is also used internally in C++Builder for iterative processing on all owned components.

Note:	For convenience use Components with ComponentCount for iterative processing. However, be aware that while the ComponentCount of a component contains the same number of items as in the Components list for that component, ComponentCount is always 1 more than the highest Components index, because the first Components index is always 0.


TComponent::ComponentState

TComponent	See also

Describes the current state of the component, indicating when a component needs to avoid certain actions.

enum Classes__34 { csLoading, csReading, csWriting, csDestroying, csDesigning, csAncestor, csUpdating, csFixups };

typedef Set<Classes__34, csLoading, csFixups>  TComponentState;

__property TComponentState ComponentState = {read=FComponentState, nodefault};

Description

Components use the ComponentState property to detect states in which certain kinds of actions are allowed or disallowed. For example, if a component needs to avoid certain behaviors at design time that it will perform at runtime, it can check for the csDesigning flag. ComponentState is read-only and its flags are set automatically by various methods, each for its own purpose.

The TComponentState type defines the set of possible state flags for the ComponentState property. The following table lists the possible values for the TComponentState type and the meaning corresponding to each flag:

Flag	Component state

csAncestor	Set if the component was introduced in an ancestor form. Only set if csDesigning is also set.
csDesigning	Design mode, meaning it is in a form being manipulated by a form designer.
csDestroying	The component is about to be destroyed.
csFixups	Set if the component is linked to a component in another form that has not yet been loaded. This flag is cleared when all pending fixups are resolved.
csLoading	Loading from a filer object.
csReading	Reading its property values from a stream.
csUpdating	The component is being updated to reflect changes in an ancestor form. Only set if csAncestor is also set.
csWriting	Writing its property values to a stream.


TComponent::ComponentStyle

TComponent

Governs the behavior of the component.

typedef Set<Classes__44, csInheritable, csCheckPropAvail>  TComponentStyle;

__property TComponentStyle ComponentStyle = {read=FComponentStyle, nodefault};

Description

ComponentStyle determines whether a component (and therefore the forms that contain it) is inheritable, and whether it needs to check its properties for readability.

The TComponentStyle type defines a set of values for the ComponentStyle property. TComponent sets the csInheritable style by default in the constructor, and most of the standard components are inheritable.

The csInheritable style indicates that the component can be inherited by a descendant form type. If any of the components in a form do not have the csInheritable style, the form cannot be used as the ancestor of an inherited form.

The csCheckPropAvail style indicates that a component needs to check its properties for readability. This is only used for OLE controls, where the Object Inspector cannot tell directly that a property is readable, and therefore displayable. Native components should not use this style.


TComponent::DesignInfo

TComponent	See also

Contains information used by the Form designer.

__property int DesignInfo = {read=FDesignInfo, write=FDesignInfo, nodefault};

Description

DesignInfo is used internally. Do not use this property in applications.


TComponent::Name

TComponent	See also 	Example

Specifies the name of the component as referenced in code.

__property System::AnsiString Name = {read=FName, write=SetName, stored=false};

Description

Use Name to change the name of a component to reflect its purpose in the current application. By default, C++Builder assigns sequential names based on the type of the component, such as 'Button1', 'Button2', and so on.


TComponent::Owner

TComponent	See also

Indicates which component owns the component.

__property TComponent* Owner = {read=FOwner};

Description

Use Owner to find the owner of a component. When one component is owned by another, the memory for the owned component is freed when its owner's memory is freed. This means that when a form is destroyed, all the components on the form are also destroyed.

By default, a form owns all components that are on it. In turn, the form is owned by the application. Thus when the memory for the application itself is freed, the memory for the form (and all its owned components) is also freed.

The owner of a component is determined by the parameter passed to the Create method when the component is constructed. For components created in the form designer, the owner is passed automatically to the constructor.


TComponent.Tag
TComponent::Tag

TComponent

Stores an integer value as part of a component.

__property int Tag = {read=FTag, write=FTag, default=0};

Description

Tag has no predefined meaning. The Tag property is provided for the convenience of storing additional integer value or pointer information for special needs in an application. For example, use the Tag property when implementing case statements with a component.


TComponent::VCLComObject

TComponent	See also

Represents information used internally for components that support COM.

__property void * VCLComObject = {read=FVCLComObject, write=FVCLComObject};

Description

VCLComObject is for internal use only. To access the interfaces implemented by a VCL COM component, use the ComObject property instead.


TComponent methods

TComponent	Alphabetically	Legend

In TComponent

_AddRef

_Release

~TComponent

ChangeName

DefineProperties

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetChildOwner

GetChildParent

GetChildren

GetIDsOfNames

GetNamePath

GetOwner

GetParentComponent

GetTypeInfo

GetTypeInfoCount

HasParent

InsertComponent

Invoke

Loaded

Notification

QueryInterface

ReadState

RemoveComponent

SafeCallException

SetAncestor

SetChildOrder

SetDesigning

SetName

SetParentComponent

TComponent

Updated

UpdateRegistry

Updating

ValidateContainer

ValidateInsert

ValidateRename

WriteState

Derived from TPersistent

Assign

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TComponent methods

TComponent	By object	Legend

_AddRef

_Release

~TComponent

Assign

ChangeName

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DefineProperties

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetChildOwner

GetChildParent

GetChildren

GetIDsOfNames

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetOwner

GetParentComponent

GetTypeInfo

GetTypeInfoCount

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invoke

Loaded

MethodAddress

MethodName

NewInstance

Notification

QueryInterface

ReadState

RemoveComponent

SafeCallException

SetAncestor

SetChildOrder

SetDesigning

SetName

SetParentComponent

TComponent

Updated

UpdateRegistry

Updating

ValidateContainer

ValidateInsert

ValidateRename

WriteState


TComponent::ChangeName

TComponent	See also

Sets the private, internal storage for the Name property to the string passed in NewName.

void __fastcall ChangeName(const System::AnsiString NewName);

Description

Do not use ChangeName directly in an application.  Instead, use the Name property.

Note:	The SetName method uses ChangeName to change the component's name. ChangeName is not virtual; do not override it. When overriding SetName be sure to call the inherited SetName.


TComponent::TComponent

TComponent	See also

Allocates memory and constructs a safely initialized instance of a component.

__fastcall virtual TComponent(TComponent* AOwner);

Description

TComponent

•	establishes the relationship of a component and its Owner, as indicated by the AOwner parameter

•	sets the ComponentStyle property to csInheritable, meaning that the component can be inherited by a descendant form type

It is not necessary to explicitly create components added in the form designer. These components are created automatically when the application is run, and they are destroyed when the application is closed.

For components created programmatically, that is, not created in the form designer, call the constructor indirectly using the new keyword and pass in an owner component as the AOwner parameter. The owner will dispose of the component when the owner is destroyed. If the component is not owned, then call delete so that it is destroyed.

Note:	When passing in this, consider what this references. If a component creates another component in one of its methods, then this refers to the first component and not the component being created, which will be owned by the first component.


TComponent::DefineProperties

TComponent	See also

Designates methods for storing an object's unpublished data on a stream such as a form file.

virtual void __fastcall DefineProperties(TFiler* Filer);

Description

TComponent overrides the DefineProperties method defined in TPersistent to define "fake" Top and Left properties. These are defined so that a non-visual component can be manipulated at design-time. However, the Top and Left properties are hidden, that is, they are not published because non-visual components do not appear at run-time.

DefineProperties is virtual, so descendent classes can override it. When writing or overriding a DefineProperties method, be aware that the Ancestor property of Filer might be set, and that this property can determine whether it is appropriate to write or not write properties.

DefineProperties is called automatically as part of the component streaming system; do not call it directly.


TComponent::~TComponent

TComponent	See also

Disposes of the component and its owned components.

__fastcall virtual ~TComponent(void);

Description

Do not call ~TComponent directly. Use the delete keyword, which takes an indirect reference to the component, instead.

Before freeing the instance of the component, ~TComponent sends out an opRemove notification so that any other component with dependencies on the component can make appropriate adjustments.  ~TComponent then frees all components that it owns (all components in the indexed Components property).  Finally it removes the Component from the Components property of its Owner and frees the memory allocated to the component.

Never explicitly free a component in one of its own event handlers, nor free a component from the event handler of a component that it owns or contains.

To destroy a form, call its Release method. Release waits for all the form’s event handlers and the event handlers of the form’s components to finish executing before destroying the form.

Note:	A form owns all the controls and non-visual components that are placed on it in design mode. When it is freed, all of these components are automatically freed as well. By default, all forms are owned by the global Application object. When an application terminates, it frees the global Application object, which frees all forms. For objects that are not components, and for components created with a NULL owner, be sure to call delete after finishing with the object; otherwise the memory allocated for the object will be lost until the application terminates.


TComponent::~TComponent
TComponent::DestroyComponents

TComponent	See also

Ensures that owned components are automatically destroyed by their owner.

void __fastcall DestroyComponents(void);

Description

DestroyComponents iterates through the components owned by the component, removing each from the list of owned components and destroying it.

It is not necessary to call DestroyComponents directly. DestroyComponents is automatically called in the destructor sequence that begins with a call to delete and ends with the object destroying itself.


TComponent::~TComponent
TComponent::Destroying

TComponent	See also

Indicates that the component and its owned components are about to be destroyed.

void __fastcall Destroying(void);

Description

Destroying sets the csDestroying flag in the ComponentState property.  It then calls the Destroying method for each owned component so that their csDestroying flags are also set. If csDestroying is already set, Destroying does nothing.

It is not necessary to call Destroying directly. Destroying is automatically called in the destructor sequence that begins with a call to delete and ends with the object destroying itself.


TComponent::FindComponent

TComponent	See also 	Example

Indicates whether or not a given component is owned by the component.

TComponent* __fastcall FindComponent(const System::AnsiString AName);

Description

FindComponent returns the component in the Components array property with the name that matches the string in the AName parameter. Use FindComponent to determine whether a given component is owned by another.

FindComponent is not case sensitive.


TComponent::FreeNotification

TComponent	See also

Ensures that AComponent is notified that the component is going to be destroyed.

void __fastcall FreeNotification(TComponent* AComponent);

Description

Use FreeNotification when a component in a different form is assigned to a property of the component.

FreeNotification must be called for components in other forms that have references to the component. For components in the same form as the component, the Notification method is called automatically.


TComponent::FreeOnRelease

TComponent

Frees the interface reference for components that were created from COM classes.

void __fastcall FreeOnRelease(void);

Description

FreeOnRelease is called when an interface implemented by the component is released. FreeOnRelease is used internally and calls the corresponding interface method. It should not be necessary to call FreeOnRelease directly.


TComponent::GetChildOwner

TComponent	See also

Returns the owner of a child component being read from a stream.

DYNAMIC TComponent* __fastcall GetChildOwner(void);

Description

In TComponent, GetChildOwner returns NULL by default, meaning that the owner is assumed to be the root component currently being read (usually a form). The Owner of a component is responsible for destroying it.

GetChildOwner is used internally by the component streaming system in C++Builder. It is rarely necessary to call it directly.


TComponent::GetChildParent

TComponent	See also

Returns the parent, or if there is no parent, returns the owner of a child component being read from a stream.

DYNAMIC TComponent* __fastcall GetChildParent(void);

Description

By default GetChildParent for TComponent returns this. If GetChildParent returns NULL, the parent is assumed to be the root component currently being read (usually a form).

GetChildParent is used internally in the C++Builder component streaming system. It is not necessary to call it directly.


TComponent::GetChildren

TComponent	See also

Provides the interface for a method that windowed controls use to return their child components.

DYNAMIC void __fastcall GetChildren(TGetChildProc &Proc, TComponent* Root);

Description

GetChildren is introduced in TComponent for the streaming system that loads and saves VCL components. Descendent classes override GetChildren to return the "child" components of the component; that is, components that return this component from their GetParentComponent method.


TComponent::GetIDsOfNames

TComponent	See also

Maps a single member and an optional set of argument names to a corresponding set of integer dispatch identifiers (dispIDs).

HRESULT __stdcall GetIDsOfNames(const GUID &IID, void * Names, int NameCount, int LocaleID, void * DispIDs);

Description

GetIDsOfNames implements the IDispatch interface GetIDsOfNames method. For components that support interfaces, GetIDsOfNames calls this method for the interface supported by the component, passing the specified parameters. The returned value can be used on subsequent calls to the Invoke method.


TComponent::GetNamePath

TComponent	See also

Returns a string used by the Object Inspector.

DYNAMIC System::AnsiString __fastcall GetNamePath(void);

Description

GetNamePath is for internal use only. It is used to determine the text to display in the Object Inspector for the name of the object being edited. GetNamePath is introduced in TPersistent so that descendants like collections can appear in the Object Inspector. TComponent overrides GetNamePath to return the component name. Do not call GetNamePath directly.


TComponent::GetOwner

TComponent	See also

Returns the owner of a component.

DYNAMIC TPersistent* __fastcall GetOwner(void);

Description

GetOwner is used by the GetNamePath method to find the owner of a component. GetNamePath and GetOwner are introduced in TPersistent so that descendants like collections can appear in the Object Inspector. For TComponent it is the value of the Owner property.


TComponent::GetParentComponent

TComponent	See also

Returns NULL for TComponent.

DYNAMIC TComponent* __fastcall GetParentComponent(void);

Description

The GetParentComponent method is introduced in TComponent for the streaming system that loads and saves VCL components. Descendent classes can override GetParentComponent to return the appropriate parent for their particular type of component.


TComponent::GetTypeInfo

TComponent	See also

Retrieves the type information for an object.

HRESULT __stdcall GetTypeInfo(int Index, int LocaleID, void *TypeInfo);

Description

GetTypeInfo implements the IDispatch interface GetTypeInfo method. For components that support interfaces, GetTypeInfo calls the GetTypeInfo method for the interface supported by the component, passing it the specified parameters.  Use the returned value to get the type information for an interface implemented by the component.


TComponent::GetTypeInfoCount

TComponent	See also

Returns the number of type information interfaces that an object provides (either 0 or 1).

HRESULT __stdcall GetTypeInfoCount(int &Count);

Description

GetTypeInfoCount implements the IDispatch interface GetTypeInfoCount method. For components that support interfaces, GetTypeInfoCount calls this method for the interface supported by the component. The out parameter points to a location that receives the number of type information interfaces provided by the object. If the object provides type information, this number is 1; otherwise the number is 0.


TComponent::HasParent

TComponent	See also

Indicates whether the component has a parent to handle its filing.

DYNAMIC bool __fastcall HasParent(void);

Description

HasParent is introduced in TComponent for the streaming system that loads and saves VCL components. It returns false for TComponent.

A return value of true indicates that some other object (a parent) is responsible for writing the object to a stream. Most commonly the parent object is a form or panel component that contains a control.

It is rarely necessary to override HasParent. Any child component that returns true from HasParent must also implement the GetParentComponent and SetParentComponent methods.


TComponent::InsertComponent

TComponent	See also 	Example

Establishes the component as the owner of a specified component.

void __fastcall InsertComponent(TComponent* AComponent);

Description

InsertComponent adds the component passed in the AComponent parameter to the end of the Components array property. The inserted component must have no name (no specified Name property value), or the name must be unique among all others in the Components list.

When the owning component is destroyed, AComponent is destroyed also.

Components are automatically inserted and removed when visually manipulating them in the form designer. Use InsertComponent when manually adding components to another Owner component’s Components list.


TComponent::Invoke

TComponent	See also

Provides access to OLE Automation properties and methods exposed by an object that supports the IDispatch interface.

HRESULT __stdcall Invoke(int DispID, const GUID &IID, int LocaleID, Word Flags, void *Params, void * VarResult, void * ExcepInfo, void * ArgErr);

Description

Invoke implements the IDispatch interface Invoke method. Invoke is the standard mechanism for accessing the exposed properties and methods of an OLE Automation object. For components that support interfaces, Invoke calls the Invoke method for the interface supported by the component, passing it the parameters specified by the function.


TComponent::Loaded

TComponent	See also

Clears the csLoading flag in the ComponentState property indicating that the component has been loaded from a stream.

virtual void __fastcall Loaded(void);

Description

The Loaded method allows a component to initialize itself after all its parts have loaded from a stream.

When a C++Builder application loads a form from its form file, for example, it first constructs the form component by calling its Create constructor, then reading its property values from the form file, which is a stream. After reading all the property values for all the components, C++Builder calls the Loaded methods of each component in the order the components were created. This gives the components a chance to initialize any data that depends on the values of other components or other parts of itself.

Note:	All references to sibling components are resolved by the time Loaded is called. Loaded is the first place that sibling pointers can be used after being streamed in.


TComponent::Notification

TComponent	See also

Forwards notification messages to all owned components.

virtual void __fastcall Notification(TComponent* AComponent, TOperation Operation);

Description

Do not call the Notification method in an application.  The Notification method is called automatically when the component specified by AComponent is about to be inserted or removed, as specified by Operation. By default, components pass along the notification to their owned components, if any.

A component can, if needed, act on the notification that a component is being inserted or removed. For example, if a component has object fields or properties that contain references to other components, it can check the notifications of component removals and invalidate those references as needed.


TComponent::QueryInterface

TComponent	See also

Returns a reference to a specified interface if that interface is supported by the object.

HRESULT __stdcall QueryInterface(const GUID &IID, void *Obj);

Description

For components that support interfaces, QueryInterface calls the QueryInterface method of the interface supported by the component. QueryInterface returns a reference to the interface specified by the IID parameter, as the Obj parameter. If the component does not support the interface, the Obj parameter is NULL.


TComponent::ReadState

TComponent	See also

Reads the component’s data from a stream.

virtual void __fastcall ReadState(TReader* Reader);

Description

ReadState is part of a sequence of calls used by the streaming system that loads and saves VCL components.  It reads the values of all the component's published properties, stored data, and owned components from the reader object passed in Reader. Do not call ReadState directly.

Although ReadState is virtual, it is rarely overridden. Nevertheless, any descendent classes overriding ReadState should end with a call to the inherited ReadState method of TComponent.


TComponent::RemoveComponent

TComponent	See also 	Example

Removes a specified component specified from the component's Components list.

void __fastcall RemoveComponent(TComponent* AComponent);

Description

Components are automatically inserted and removed when visually manipulating them in the form designer. Use RemoveComponent to programmatically delete the component specified by AComponent from its Owner component.


TComponent::SafeCallException

TComponent	See also

Handles OLE exceptions.

virtual HRESULT __fastcall SafeCallException(System::TObject* ExceptObject, void * ExceptAddr);

Description

SafeCallException is used for OLE exception handling support. Classes that implement COM and OLE interfaces should override this method to handle other errors that might occur. COM and OLE classes in C++Builder override SafeCallException. TComponent calls the implementation of this method for the interface supported by the component, if one exists. If the component does not support interfaces, this method calls the inherited method, which returns E_UNEXPECTED. This is a default return value that is appropriate for classes that do not support any interfaces.


TComponent::SetAncestor

TComponent	See also

Sets or clears the ComponentState property’s csAncestor flag.

void __fastcall SetAncestor(bool Value);

Description

SetAncestor is used internally by the streaming system that loads and saves VCL components. Do not call SetAncestor directly.

SetAncestor sets or clears the csAncestor flag which indicates whether the component was introduced in an ancestor form. SetAncestor then calls the SetAncestor methods of any owned components, passing Value, so that the owned components' ComponentState properties will be synchronized with the owner's.


TComponent::SetChildOrder

TComponent	See also

Provides the interface for a method to rearrange child components.

DYNAMIC void __fastcall SetChildOrder(TComponent* Child, int Order);

Description

SetChildOrder is introduced in TComponent for the streaming system that loads and saves VCL components. TComponent::SetChildOrder does nothing. Descendent classes override SetChildOrder to change the order in which a child appears in the child component list returned by GetChildren.


TComponent::SetDesigning

TComponent	See also

Ensures that components inserted at design time have their design-mode flag set.

void __fastcall SetDesigning(bool Value);

Description

SetDesigning is used internally by the Form designer. Do not call SetDesigning directly.

SetDesigning sets the csDesigning flag in the ComponentState property if Value is true; otherwise, it removes csDesigning. SetDesigning then calls the SetDesigning methods of any owned components, passing Value, so that the owned components' ComponentState properties are synchronized with the owner's.

The InsertComponent and RemoveComponent methods call SetDesigning for inserted or removed components to ensure that their design-mode flags are set properly.


TComponent::SetName

TComponent	See also

Sets the value of the Name property.

virtual void __fastcall SetName(const System::AnsiString NewName);

Description

SetName is the virtual method used as the write part of the Name property. It calls the ChangeName method, which performs the actual name change. ChangeName is not virtual; override SetName instead when modifying the behavior of the Name property.


TComponent::SetParentComponent

TComponent	See also

Provides the interface for a method that changes the parent of a component.

DYNAMIC void __fastcall SetParentComponent(TComponent* Value);

Description

SetParentComponent is introduced in TComponent for the streaming system that loads and saves VCL components. SetParentComponent does nothing in TComponent. Descendent classes override SetParentComponent to change the value that GetParentComponent returns to match the Value parameter.


TComponent::Updated

TComponent	See also

Clears the csUpdating state in the component's ComponentState property when the component finishes updating.

DYNAMIC void __fastcall Updated(void);

Description

Do not call Updated directly. It is used internally to clear the csUpdating flag of the ComponentState property. A call to Updated always follows a call to Updating, which sets the flag.


TComponent::UpdateRegistry

TComponent

Provides the interface for a method that adds type library and version information to the Registry on components that implement COM interfaces.

virtual void __fastcall UpdateRegistry(bool Register, const System::AnsiString ClassID, const System::AnsiString ProgID) { UpdateRegistry(__classid(TComponent), Register, ClassID, ProgID);

Description

Do not call UpdateRegistry directly. It is for internal use only.


TComponent::Updating

TComponent	See also

Sets the csUpdating state in the component's ComponentState property.

DYNAMIC void __fastcall Updating(void);

Description

Do not call Updating directly. It is used internally to indicate that the component is about to be updated. A call to Updating, which sets the csUpdating flag, is always followed by a call to Updated, which clears the flag.


TComponent::ValidateContainer

TComponent	See also

Determines whether an object can be inserted into a container object.

DYNAMIC void __fastcall ValidateContainer(TComponent* AComponent);

Description

ValidateContainer is called by a component when it is about to be inserted into a container object. By default, ValidateContainer calls the ValidateInsert method of the component specified by the AComponent parameter.

Descendent components can override ValidateContainer to disallow a component from being inserted into specific containers. To disallow an insertion, throw an exception in the derived method.


TComponent::ValidateInsert

TComponent	See also

Provides the interface for a method that validates an child component before it is inserted.

DYNAMIC void __fastcall ValidateInsert(TComponent* AComponent);

Description

ValidateInsert does nothing in TComponent. Descendent classes can override it to disallow a component from accepting an object being inserted into it. By default ValidateInsert allows any object to be inserted into the component.

If a component needs to validate only certain objects, descendent classes can override ValidateInsert to filter out those objects.  To disallow an insertion, throw an exception in the derived method.


TComponent::ValidateRename

TComponent	See also

Ensures that renaming an owned component does not create name conflict.

virtual void __fastcall ValidateRename(TComponent* AComponent, const System::AnsiString CurName, const System::AnsiString NewName);

Description

ValidateRename checks to see if a component can rename one of its owned components, passed in AComponent, from its current name (CurName) to the string passed in NewName. If AComponent is NULL or NewName is already the name of a component in the Components list, ValidateRename throws an EComponentError exception.

ValidateRename is used internally when the Name property is modified. It is not necessary to call it directly.


TComponent::WriteState

TComponent	See also

Writes the component’s data to a stream.

virtual void __fastcall WriteState(TWriter* Writer);

Description

WriteState is part of a sequence of calls used by the streaming system that loads and saves VCL components. WriteState is an iterative method that writes the values of all the component's published properties and other stored data to the Writer component passed as the Writer parameter. Do not call WriteState directly.

Although WriteState is virtual, it is rarely overridden. Any descendent classes overriding WriteState should end with a call to the inherited WriteState method of TComponent.


TComponent::_AddRef

TComponent	See also

Increments the reference count for the number of interface references dependent on the component.

int __stdcall _AddRef(void);

Description

_AddRef implements the IUnknown interface method, AddRef, defined by COM. For components that support interfaces, _AddRef calls the AddRef method for the interface supported by the component. _AddRef returns the resulting value of the reference count for the component.


TComponent::_Release

TComponent	See also

Decrements the reference count for the calling interface on a object.

int __stdcall _Release(void);

Description

_Release implements the IUnknown interface method, Release, defined by COM. For components that support interfaces, _Release calls the Release method for the interface supported by the component. If the reference count on the object falls to 0, the object is freed from memory.

_Release returns the resulting value of the reference count for the component.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent


TContainedObject

Hierarchy	Properties 	Methods	See also

TContainedObject is a class that implements the IUnknown interface as an inner object in an aggregate.

Unit

axctrls

Description

TContainedObject is implemented according to the rules that apply for aggregatable (inner or contained) objects. It can be used as a base for classes that create inner, or contained, objects of an aggregate. Use TComObject or its descendants to instantiate an outer object that supports aggregation.

The following implementation rules for aggregatable (inner or contained) objects are supported by TContainedObject:

•	When an object of its type is created, the creation succeeds only for a requested interface of type IUnknown.

•	The IUnknown methods AddRef and Release delegate to the controlling IUnknown.

•	QueryInterface is implemented, in TContainedObject, only for interfaces implemented in the contained object.

•	The reference count on the inner object is incremented in the containing object.

In the C++Builder class hierarchy, TContainedObject is used as a base class for a connection point which must be an inner object in an aggregate.

Note

An aggregated COM object is an object that is composed of several COM objects. Each object implements its own behavior and interfaces, but all of the objects share the same reference count, which is that of the controller object. In the container pattern, the controller is the container object.

For more information about aggregation, controlling objects, and interfaces, see the Inside OLE, second edition, by Kraig Brockschmidt, the Microsoft Web site, or the Windows SDK Help.


TContainedObject properties

TContainedObject	Alphabetically	Legend

Derived from TAggregatedObject

Controller


TContainedObject properties

TContainedObject	By object	Legend

Controller


TContainedObject methods

TContainedObject	Alphabetically

In TContainedObject

~TContainedObject

TContainedObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TContainedObject methods

TContainedObject	By object

~TContainedObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TContainedObject


TContainedObject::TContainedObject

TContainedObject

TContainedObject creates a new TContainedObject object.

__fastcall TContainedObject(_di_IUnknown Controller) : Axctrls::TAggregatedObject(Controller) { }


TContainedObject::~TContainedObject

TContainedObject

~TContainedObject frees the memory associated with the TContainedObject object. Do not call ~TContainedObject directly. Instead, use the delete keyword on the object, which causes ~TContainedObject to be invoked automatically.

__fastcall virtual ~TContainedObject(void) { }


Accessibility

Read-only


Hierarchy

TObject

TAggregatedObject


TCollection

Hierarchy	Properties	Methods	See also

TCollection is a container for TCollectionItem objects.

Unit

classes

Description

Each TCollection holds a group of TCollectionItem objects. TCollection maintains an index of the collection items in its Items array. The Count property contains the number of items in the collection. Use the Add and Clear methods to add items to the collection and delete items from the collection.

Objects descended from TCollection can contain objects descended from TCollectionItem. For example, a TDBGridColumns object contains TColumn objects; these two classes are used by TDBGrid to represent grid columns. The following table lists each descendant of TCollection with the corresponding descendant TCollectionItem and the control component that uses each pair. Except for TQueryTableProducer and TWebDispatcher, the controls descend from TWinControl.

TCollection	TControl	TCollectionItem

TCheckConstraints	TCheckConstraint	controls that use TField

TCookieCollection	TCookie	HTTP response objects

TCoolBands	TCoolBand	TCoolBar

TDBGridColumns	TColumn	TDBGrid

TDisplayDims	TDisplayDim	TDecisionGrid

TFieldDefs	TFieldDef	TDataSet

THeaderSections	THeaderSection	THeaderControl

TIndexDefs	TIndexDef	TTable

THTMLTableColumns	THTMLTableColumn	TQueryTableProducer

TListColumns	TListColumn	TListView

TStatusPanels	TStatusPanel	TStatusBar

TWebActionItems	TWebActionItem	TWebDispatcher

The controls that use TCollection and TCollectionItem descendants have a published property that holds a collection. (For example, the Panels property of TStatusBar holds a TStatusPanels.) A standard property editor, referred to generically as the Collection editor, can be invoked from the Object Inspector to edit the items in the collection.


TCollection properties

TCollection	Alphabetically	Legend

In TCollection

Count

ItemClass

Items


TCollection properties

TCollection	By object	Legend

Count

ItemClass

Items


TCollection::Count

TCollection	See also 	Example

Returns the number of items in the collection.

__property int Count = {read=GetCount, nodefault};

Description

Count contains the number of items in the Items array. Since Items is indexed starting with 0, the value of Count is always one greater than the index of the last member of Items.


TCollection::ItemClass

TCollection	See also

Indicates the class to which the collection’s items belong.

__property System::TMetaClass* ItemClass = {read=FItemClass};

Description

ItemClass returns the class (descended from TCollectionItem) to which the items in the collection belong. For example, in an instance of the TCollection descendant THeaderSections, the ItemClass property returns THeaderSection.


TCollection::Items

TCollection	See also

Provides indexed access to the items in the collection.

__property TCollectionItem* Items[int Index] = {read=GetItem, write=SetItem};

Description

Use Items to access individual items in the collection. The value of the Index parameter corresponds to the Index property of TCollectionItem. It represents the position of the item in the collection.


TCollection methods

TCollection	Alphabetically

In TCollection

~TCollection

Add

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

TCollection

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCollection methods

TCollection	By object

~TCollection

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCollection


TCollection.Add

TCollection	See also

Creates a new TCollectionItem instance and adds it to the Items array.

TCollectionItem* __fastcall Add(void);

Description

Call Add to create an item in the collection. The new item is placed at the end of the Items array.

Add returns the new collection item.


TCollection::Assign

TCollection	See also

Copies the contents of another collection to the object where the method is executed.

virtual void __fastcall Assign(TPersistent* Source);

Description

Use Assign to copy the contents of one TCollection instance to another. The Assign method deletes all items from the destination collection (the object where it is executed), then adds a copy of each item in the Source collection’s Items array.


TCollection::BeginUpdate

TCollection	See also 	Example

Suspends screen repainting.

void __fastcall BeginUpdate(void);

Description

The BeginUpdate method suspends screen repainting until the EndUpdate method is called. Use BeginUpdate to speed processing and avoid flicker while items are added to or deleted from a collection.


TCollection::Clear

TCollection	See also

Deletes all items from the collection.

void __fastcall Clear(void);

Description

Clear empties the Items array and destroys each TCollectionItem.


TCollection::TCollection

TCollection	See also

Creates and initializes a collection.

__fastcall TCollection(System::TMetaClass* ItemClass);

Description

Do not call TCollection directly. Instead, use the keyword new, which returns an indirect reference to the new collection.

The TCollection method takes the name of a TCollectionItem descendant class as a parameter. This parameter determines the class of the items created by the Add method.


TCollection::~TCollection

TCollection	See also

Destroys the collection and each item in it.

__fastcall virtual ~TCollection(void);

Description

Do not call ~TCollection directly. Instead, use the delete keyword on the object, which causes ~TCollection to be invoked automatically.

~TCollection calls the Clear method to free each item referenced in the Items array, then destroys the collection itself.


TCollection::EndUpdate

TCollection	See also 	Example

Re-enables screen repainting.

void __fastcall EndUpdate(void);

Description

Use EndUpdate to re-enable screen repainting that was turned off with the BeginUpdate method.


TCollection::FindItemID

TCollection	See also

Returns the item with the specified ID.

TCollectionItem* __fastcall FindItemID(int ID);

Description

The FindItemID method returns the item in the collection whose ID property is passed to it as a parameter. If no item has the specified ID, FindItemID returns NULL.


TCollection::Insert

TCollection	See also

Creates a new TCollectionItem instance and adds it to the Items array.

TCollectionItem* __fastcall Insert(int Index);

Description

Call Insert to add a new item at a specified position in the collection. Existing items (starting from the specified position) are moved up in the Items array.

Insert returns the new collection item.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TCollectionItem

Hierarchy	Properties	Methods	See also

TCollectionItem represents an item in a collection.

Unit

classes

Description

A TCollection holds a group of TCollectionItem objects. TCollectionItems are created and destroyed by TCollection’s Add and Clear methods. Each TCollectionItem has a Collection property that points to the TCollection object to which the item belongs.

Objects descended from TCollection can contain objects descended from TCollectionItem. For example, a TDBGridColumns object contains TColumn objects; these two classes are used by TDBGrid to represent grid columns. For a complete list of TCollection and TCollectionItem descendants, see TCollection.


TCollectionItem properties

TCollectionItem	Alphabetically	Legend

In TCollectionItem

Collection

DisplayName

ID

Index


TCollectionItem properties

TCollectionItem	By object	Legend

Collection

DisplayName

ID

Index


TCollectionItem::Collection

TCollectionItem

Specifies the TCollection instance to which the TCollectionItem belongs.

__property TCollection* Collection = {read=FCollection, write=SetCollection};

Description

Each TCollectionItem belongs to the TCollection which creates it. The Collection property points to the collection object to which the item belongs.


TCollectionItem::DisplayName

TCollectionItem

The name displayed in the Collection editor.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

DisplayName is the string that represents the item in the Collection editor. When the item is selected in the Collection editor, the DisplayName can also appear in the Object Inspector as the value of another property (for example, as the Text property of THeaderSection or TStatusPanel). By default, DisplayName is the name of the TCollectionItem descendant class of which the item is an instance.


TCollectionItem::ID

TCollectionItem	See also

A unique, permanent index for the item.

__property int ID = {read=FID, nodefault};

Description

In most cases, ID is the value of the item’s Index property when it was first added to the collection. But, unlike Index values, ID values are never changed or reassigned. If an item is removed from a collection, its ID not used again.

An item’s Index may change when other items are deleted from the collection or when items are rearranged. ID provides a unique identifier for each item that is unchanged for the life of the collection.


TCollectionItem::Index

TCollectionItem	See also

Returns the item’s position in the Items array of TCollection.

__property int Index = {read=GetIndex, write=SetIndex, nodefault};

Description

Each TCollectionItem is indexed in the Items array of the TCollection to which it belongs. The Index property of the TCollectionItem contains the item’s index value in that array.

Items is a zero-based array. The first member of the collection has an index value of 0, the second member has an index value of 1, and so forth.


TCollectionItem methods

TCollectionItem	Alphabetically

In TCollectionItem

~TCollectionItem

TCollectionItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCollectionItem methods

TCollectionItem	By object

~TCollectionItem

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCollectionItem


TCollectionItem::TCollectionItem

TCollectionItem	See also

Creates and initializes a TCollectionItem instance.

__fastcall virtual TCollectionItem(TCollection* Collection);

Description

Do not call TCollectionItem directly. Instead, use the keyword new, which returns an indirect reference to the new item.

The TCollectionItem method takes as a parameter the name of a TCollection instance. TCollectionItem is called by TCollection’s Add method.


TCollectionItem::~TCollectionItem

TCollectionItem	See also

Destroys the TCollectionItem instance and frees its memory.

__fastcall virtual ~TCollectionItem(void);

Description

Do not call ~TCollectionItem directly. Instead, use the delete keyword on the object, which causes ~TCollectionItem to be invoked automatically.

~TCollectionItem is called indirectly by TCollection’s Clear method.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


 TColorDialog

Hierarchy	Properties	Methods	Events

TColorDialog displays a modal color-selection dialog.

Unit

dialogs

Description

The TColorDialog component displays a Windows dialog box for selecting colors. The dialog does not appear at runtime until it is activated by a call to the Execute method. When the user selects a color and clicks OK, the dialog closes and the selected color is stored in the Color property.


TColorDialog properties

TColorDialog	Alphabetically	Legend

In TColorDialog

Color

CustomColors

Options

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TColorDialog properties

TColorDialog	By object	Legend

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

CustomColors

DesignInfo

HelpContext

Name

Options

Owner

Tag

VCLComObject


TColorDialog::Color

TColorDialog	Example

Returns the selected color.

__property Graphics::TColor Color = {read=FColor, write=FColor, default=0};

Description

When the user selects a color in the dialog box and clicks OK, the selected color becomes the value of the Color property. To make a default color appear in the dialog when it opens, assign a value to Color in the Object Inspector or in program code.


TColorDialog::CustomColors

TColorDialog

Determines which custom colors are available in the dialog box.

__property Classes::TStrings* CustomColors = {read=FCustomColors, write=SetCustomColors};

Description

Each custom color is represented as a string of the form ColorX=HexValue. For example, the following string sets the first custom color.

ColorA=808022

Up to 16 custom colors (ColorA through ColorP) can be set.


TColorDialog::Options

TColorDialog

Specifies options and default appearance for the dialog.

enum TColorDialogOption { cdFullOpen, cdPreventFullOpen, cdShowHelp, cdSolidColor, cdAnyColor };

typedef Set<TColorDialogOption, cdFullOpen, cdAnyColor>  TColorDialogOptions;

__property TColorDialogOptions Options = {read=FOptions, write=FOptions, default=0};

Description

Use the Options property to customize the appearance and functionality of the dialog. The possible values of Options are

Value	Meaning

cdFullOpen	Displays the custom color options when the dialog opens.

cdPreventFullOpen	Disables the Define Custom Colors button in the dialog, so that the user cannot define new colors.

cdShowHelp	Adds a Help button to the dialog.

cdSolidColor	Directs Windows to use the nearest solid color to the color chosen.

cdAnyColor	Allows the user to select non-solid colors (which may have to be approximated by dithering).

By default, all of these options are off.


TColorDialog events

TColorDialog	Alphabetically	Legend

Derived from TCommonDialog

OnClose

OnShow


TColorDialog events

TColorDialog	By object	Legend

OnClose

OnShow


TColorDialog methods

TColorDialog	Alphabetically

In TColorDialog

~TColorDialog

Execute

TColorDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TColorDialog methods

TColorDialog	By object

~TColorDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TColorDialog


TColorDialog::TColorDialog

TColorDialog	See also

Creates and initializes a color-selection dialog.

__fastcall virtual TColorDialog(Classes::TComponent* AOwner);

Description

Do not call TColorDialog directly. Instead, use the keyword new, which returns an indirect reference to the new item.

TColorDialog generates a TColorDialog instance and initializes the CustomColors property.


TColorDialog::~TColorDialog

TColorDialog	See also

Destroys the color-selection dialog and frees its memory.

__fastcall virtual ~TColorDialog(void);

Description

Do not call ~TColorDialog directly. Instead, use the delete keyword on the object, which causes ~TColorDialog to be invoked automatically.


TColorDialog::Execute

TColorDialog 	See also	Example

Displays the color-selection dialog.

virtual bool __fastcall Execute(void);

Description

Execute opens the color-selection dialog, returning true when the user selects a color and clicks OK, or false when the user cancels.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog


TColumnTitle

Hierarchy	Properties	Methods	See also

TColumnTitle represents the title of a data-grid column (TColumn).

Unit

dbgrids

Description

TDBGrid uses a TDBGridColumns to maintain a collection of TColumn objects. Each TColumn has an associated TColumnTitle that holds information about its title. The TColumnTitle instance is stored in the column’s Title property.


TColumnTitle properties

TColumnTitle	Alphabetically	Legend

In TColumnTitle

Alignment

Caption

Color

Font


TColumnTitle properties

TColumnTitle	By object	Legend

Alignment

Caption

Color

Font


TColumnTitle::Alignment

TColumnTitle	See also

Specifies how text is aligned within the column title.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=GetAlignment, write=SetAlignment, stored=IsAlignmentStored, nodefault};

Description

These are the possible values of Alignment:

Value	Meaning

taLeftJustify	Align text on the left side of the column.

taCenter	Center text in the column.

taRightJustify	Align text on the right side of the column.


TColumnTitle::Caption

TColumnTitle	See also

Specifies the text that appears at the top of the column.

__property System::AnsiString Caption = {read=GetCaption, write=SetCaption, stored=IsCaptionStored}

Description

The Caption property contains a text string that identifies the column. If the dgTitles flag is set in the data grid’s Options property, the title appears on the form at runtime.

If the FieldName property is set in TColumn, the Caption default value comes from Field::DisplayLabel, which itself defaults to FieldName.


TColumnTitle::Color

TColumnTitle

Specifies the background color for the column title.

__property Graphics::TColor Color = {read=GetColor, write=SetColor, stored=IsColorStored, nodefault};

Description

The Color property determines the background color of the column title. You can set Color to one of the constants defined in the Graphics unit (such as clBlue), or to an explicit RGB integer value. The default value is the grid’s FixedColor property.


TColumnTitle::Font

TColumnTitle	See also

Controls the font in which the column title displays its caption.

__property Graphics::TFont* Font = {read=GetFont, write=SetFont, stored=IsFontStored};};

Description

The Font property points to a TFont object that determines typographic attributes of text displayed in the column title. The default value is the grid’s TitleFont property.


TColumnTitle methods

TColumnTitle	Alphabetically

In TColumnTitle

~TColumnTitle

Assign

DefaultAlignment

DefaultCaption

DefaultColor

DefaultFont

RestoreDefaults

TColumnTitle

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TColumnTitle methods

TColumnTitle	By object

~TColumnTitle

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultAlignment

DefaultCaption

DefaultColor

DefaultFont

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

TColumnTitle


TColumnTitle::Assign

TColumnTitle	See also

Copies the contents of the source column title to a new column title.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the Alignment, Color, Caption, and Font values of the source object to another column title.


TColumnTitle::TColumnTitle

TColumnTitle	See also

Creates and initializes a column title.

__fastcall TColumnTitle(TColumn* Column);

Description

Do not call TColumnTitle directly. Instead, use the keyword new, which returns an indirect reference to the new item.

TColumnTitle takes a TColumn instance as its argument.


TColumnTitle::DefaultAlignment

TColumnTitle	See also

Returns the default alignment of the column title.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

Classes::TAlignment __fastcall DefaultAlignment(void);

Description

DefaultAlignment returns the alignment for the column that should be used if the Alignment property is not explicitly set. The DefaultAlignment property for TColumnTitle always returns taLeftJustify. Descendants of TColumnTitle can override this to compute the default alignment in an appropriate way.


TColumnTitle::DefaultCaption

TColumnTitle	See also

Returns the default caption of the column title.

System::AnsiString __fastcall DefaultCaption();

Description

DefaultCaption returns the DisplayLabel of the TField object associated with the column. If there is no dataset field associated with the column (that is, if the column’s Field property is empty), it returns the column’s FieldName.


TColumnTitle::DefaultColor

TColumnTitle	See also

Returns the default background color for the column title.

Graphics::TColor __fastcall DefaultColor(void);

Description

Use DefaultColor to determine the background color of the column title if the Color property is not explicitly set. DefaultColor returns the FixedColor of the data grid to which the column belongs. If the column has no associated data grid, DefaultColor returns clBtnFace.


TColumnTitle::DefaultFont

TColumnTitle	See also

Returns the default font for the column title.

Graphics::TFont* __fastcall DefaultFont(void);

Description

Use DefaultColor to determine the font of the column title if the Font property is not explicitly set. DefaultFont returns the TitleFont of the data grid to which the column belongs. If the column has no associated data grid, DefaultFont returns the current value of the associated column’s Font property.


TColumnTitle::~TColumnTitle

TColumnTitle	See also

Destroys the column and frees its memory.

__fastcall virtual ~TColumnTitle(void);

Description

Do not call ~TColumnTitle directly. Instead, use the delete keyword on the object, which causes ~TColumnTitle to be invoked automatically.

~TColumnTitle eliminates the TColumnTitle instance along with its associated font (TFont).


TColumnTitle::RestoreDefaults

TColumnTitle	See also

Restores the column title’s default settings.

virtual void __fastcall RestoreDefaults(void);

Description

RestoreDefaults reinitializes the Caption and Font properties.


Scope

Published


Hierarchy

TObject

TPersistent


TColumnTitle example

TColumnTitle


TColumn

Hierarchy	Properties	Methods	See also

TColumn represents a column in a data grid (TDBGrid).

Unit

dbgrids

Description

Each TDBGrid uses a TDBGridColumns to maintain a collection of TColumn objects.


TColumn properties

TColumn	Alphabetically	Legend

In TColumn

Alignment

AssignedValues

ButtonStyle

Color

DisplayName

DropDownRows

Field

FieldName

Font

Grid

ImeMode

ImeName

PickList

PopupMenu

ReadOnly

Title

Width

Derived from TCollectionItem

Collection

ID

Index


TColumn properties

TColumn	By object	Legend

Alignment

AssignedValues

ButtonStyle

Collection

Color

DisplayName

DropDownRows

Field

FieldName

Font

Grid

ID

ImeMode

ImeName

Index

PickList

PopupMenu

ReadOnly

Title

Width


TColumn::Alignment

TColumn	See also

Specifies how text is aligned within the column.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=GetAlignment, write=SetAlignment, stored=IsAlignmentStored, nodefault};

Description

These are the possible values of Alignment:

Value	Meaning

taLeftJustify	Align text on the left side of the column.

taCenter	Center text in the column.

taRightJustify	Align text on the right side of the column.


TColumn::AssignedValues

TColumn	See also

Indicates which TColumn and TColumnTitle properties have been set.

enum TColumnValue { cvColor, cvWidth, cvFont, cvAlignment, cvReadOnly, cvTitleColor, cvTitleCaption, cvTitleAlignment, cvTitleFont, cvImeMode, cvImeName };

typedef Set<TColumnValue, cvColor, cvImeName>  TColumnValues;

__property TColumnValues AssignedValues = {read=FAssignedValues, nodefault};

Description

The read-only AssignedValues lists properties of the column and its title (TColumnTitle) which have been set or whose default values have been changed. AssignedValues is a set of zero or more of the following:

Value	Indicates changes to

cvColor	The column’s Color property.

cvWidth	The column’s Width property.

cvFont	The column’s Font property.

cvAlignment	The column’s Alignment property.

cvReadOnly	The column’s ReadOnly property.

cvTitleColor	The column title’s Color property.

cvTitleCaption	The column title’s Caption property.

cvTitleAlignment	The column title’s Alignment property.

cvTitleFont	The column title’s Font property.

cvImeMode	The column’s ImeMode property.

cvImeName	The column’s ImeName property.

For example, if AssignedValues includes cvColor and cvTitleCaption, then the column’s font and title caption have been changed and will no longer track with changes made to their default source.

Many column properties obtain their values from external sources, such as properties of the associated TField objects. Until a value is assigned to a column property, changes made to the property’s default source will be reflected by the column. After assignment, the column property is independent of its default source.


TColumn::ButtonStyle

TColumn	See also

Determines whether and how the user can select values for the column from a list.

enum TColumnButtonStyle { cbsAuto, cbsEllipsis, cbsNone };

__property TColumnButtonStyle ButtonStyle = {read=FButtonStyle, write=SetButtonStyle, default=0};

Description

The ButtonStyle property determines how users can edit the data of a data-grid column. These are the possible values of ButtonStyle:

Value	Meaning

cbsAuto	If the column is associated with a lookup field or has a value assigned to its PickList property, the grid displays a combo box in the column. The user can choose a value from the drop-down list.

cbsEllipsis	The column displays an ellipsis button that the user can click to choose a value. Clicking the ellipsis button triggers an OnEditButtonClick event.

cbsNone	No combo box or ellipsis button is provided. The user cannot select the column’s content from a list.


TColumn::Color

TColumn

The background color for the column.

__property Graphics::TColor Color = {read=GetColor, write=SetColor, stored=IsColorStored, nodefault};

Description

The Color property determines the background color of the data-grid column. You can set Color to one of the constants defined in the Graphics unit (such as clBlue), or to an explicit RGB integer value.


TColumn::DisplayName

TColumn	See also

DisplayName returns FieldName if not blank, otherwise it returns TField::DisplayName.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

Use DisplayName when displaying a string that represents the field to the user. For example, when raising an exception concerning the field, format an error string that includes the DisplayName to refer to the field.


TColumn::DropDownRows

TColumn	See also

The number of lines displayed in the column’s drop-down list.

__property Cardinal DropDownRows = {read=FDropDownRows, write=FDropDownRows, default=7};

Description

DropDownRows determines the number of lines of text displayed in the drop-down list associated with the column. This property is used only if ButtonStyle is set to cbsAuto and the column has a lookup field or pick list associated with it.


TColumn::Field

TColumn	See also

The TField instance represented by the column.

__property Db::TField* Field = {read=GetField, write=SetField};

Description

Field points to the TField object that corresponds to the dataset field displayed in the column. If the column does not correspond to a field in the dataset (for example, a calculated field), the value of Field can be NULL.


TColumn::FieldName

TColumn	See also

The name of the field represented by the column.

__property System::AnsiString FieldName = {read=FFieldName, write=SetFieldName};

Description

Setting FieldName changes the Field property so that it points to the dataset field with the same name. If the dataset does not have a field with the same name, Field is set to NULL.


TColumn::Font

TColumn	See also

Controls the font in which the column displays its data.

__property Graphics::TFont* Font = {read=GetFont, write=SetFont, stored=IsFontStored};

Description

The Font property points to a TFont object that determines typographic attributes of text displayed in the column.


TColumn::Grid

TColumn	See also

Specifies the grid that contains the column.

__property TCustomDBGrid* Grid = {read=GetGrid};

Description

Use the Grid property to access the grid that contains the column.


TColumn::ImeMode

TColumn	See also

ImeMode determines the behavior of the input method editor (IME) when the column is edited.

enum TImeMode { imDisable, imClose, imOpen, imDontCare, imSAlpha, imAlpha, imHira, imSKata, imKata, imChinese, imSHanguel, imHanguel };

__property Controls::TImeMode ImeMode = {read=GetImeMode, write=SetImeMode, stored=IsImeModeStored, nodefault};

Description

Set ImeMode to configure the way an IME processes user keystrokes when the user is editing the column. An IME is a front-end input processor for Asian language characters. The IME hooks all keyboard input, converts it to Asian characters in a conversion window, and sends the converted characters or strings on to the application.

ImeMode allows the type of conversion performed by the IME to be tailored to the input expected for the column. For example, a column that only accepts numeric input might specify an ImeMode of imClose, as no conversion is necessary for numeric input.

ImeMode can have one of the following values:

Value	Meaning

imDisable	Shut down the IME. imDisable has no effect on Chinese, Taiwanese, or Korean IMEs.

imClose	Close the IME conversion window, but leave the IME running in the background. The IME can be re-activated by a hot key combination.

imOpen	Open the IME conversion window. The conversion mode is the last conversion mode used by the IME.

imDontCare	Launch the IME if it is disabled. The conversion mode is the last conversion mode used by the IME.

imSAlpha	Open the IME conversion window and set the conversion mode to accept single-width Roman alphabet input.

imAlpha	Open the IME conversion window and set the conversion mode to accept double-width Roman alphabet input.

imHira	Open the IME conversion window and set the conversion mode to double-width Hiragana. imHira is available only for Japanese IMEs.

imSKata	Open the IME conversion window and set the conversion mode to single-width Katakana (Hankaku Katakana). imSKata is available only for Japanese IMEs.

imKata	Open the IME conversion window and set the conversion mode to double-width Katakana (Zenkaku Katakana). imKata is available only for Japanese IMEs.

imChinese	Open the IME conversion window and set the conversion mode to double-width Chinese. imChinese is available only for Chinese IMEs.

imSHanguel	Open the IME conversion window and set the conversion mode to single-width Hanguel. imSHanguel is available only for Korean IMEs.

imHanguel	Open the IME conversion window and set the conversion mode to double-width Hanguel. imHanguel is available only for Korean IMEs.


TColumn::ImeName

TColumn	See also

ImeName specifies the input method editor (IME) to use for converting keyboard input to Asian language characters.

__property System::AnsiString ImeName = {read=GetImeName, write=SetImeName, stored=IsImeNameStored};

Description

Set ImeName to specify which IME to use for converting keystrokes when the user is editing the column. An IME is a front-end input processor for Asian language characters. The IME hooks all keyboard input, converts it to Asian characters in a conversion window, and sends the converted characters or strings on to the application.

ImeName must specify one of the IMEs that has been installed through the Windows control panel. The property inspector provides a drop-down list of all currently installed IMEs on the system. At runtime, applications can obtain a list of currently installed IMEs from the global Screen variable.

If ImeName specifies an unavailable IME, the IME that was active when the application started is used instead. No exception is generated.


TColumn::PickList

TColumn	See also

A list of values that the user can select for the column.

__property Classes::TStrings* PickList = {read=GetPickList, write=SetPickList};

Description

The PickList property points to a TStrings object. If ButtonStyle is set to cbsAuto, these strings appear in the drop-down list associated with the column.


TColumn::PopupMenu

TColumn	See also

The PopupMenu property identifies the pop-up menu associated with the column.

__property Menus::TPopupMenu* PopupMenu = {read=FPopupMenu, write=SetPopupMenu};

Description

Assign a value to PopupMenu to make a pop-up menu appear when the user clicks the right mouse button on the column. If the TPopupMenu’s AutoPopup property is true, the pop-up menu appears automatically. If the menu’s AutoPopup property is false, display the menu with a call to its Popup method.


TColumn::ReadOnly

TColumn	See also

Determines whether data displayed in the column is editable.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, stored=IsReadOnlyStored, nodefault};

Description

If ReadOnly is set to true, data displayed in the column cannot be changed by the user at runtime. If ReadOnly is set to false (and the data grid’s Options property includes the dgEditing flag), users can edit data directly from the grid.


TColumn::Title

TColumn	See also

The TColumnTitle that represents the column’s title.

__property TColumnTitle* Title = {read=FTitle, write=SetTitle};

Description

The Title property points to a TColumnTitle object that determines attributes of the column’s title. If FieldName is set, the value of FieldName becomes the default column title (TColumnTitle::Caption).

The title (TColumnTitle::Caption) appears at runtime only if the dgTitles flag is set in the data grid’s Options property.


TColumn::Width

TColumn	See also

The width of the column.

__property int Width = {read=GetWidth, write=SetWidth, stored=IsWidthStored, nodefault};

Description

The Width property determines the width of the column, in pixels. If the dgColumnResize flag is set in the data grid’s Options property, users can resize the column at runtime.


TColumn methods

TColumn	Alphabetically

In TColumn

~TColumn

Assign

DefaultAlignment

DefaultColor

DefaultFont

DefaultImeMode

DefaultImeName

DefaultReadOnly

DefaultWidth

RestoreDefaults

TColumn

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TColumn methods

TColumn	By object

~TColumn

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultAlignment

DefaultColor

DefaultFont

DefaultHandler

DefaultImeMode

DefaultImeName

DefaultReadOnly

DefaultWidth

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

TColumn


TColumn::Assign

TColumn	See also

Copies the contents of the source column to a new column.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign creates a new column with the same FieldName, Title, DropDownRows, ButtonStyle, and PickList values as the source object. Color, Width, Font, Alignment, and ReadOnly are also copied if AssignedValues indicates that they have been changed.


TColumn::TColumn

TColumn	See also

Creates and initializes a data-grid column.

__fastcall virtual TColumn(Classes::TCollection* Collection);

Description

Do not call TColumn directly. Instead, use the keyword new, which returns an indirect reference to the new item.

TColumn should take a TDBGridColumns instance as its argument. It creates a data-grid column along with its title (TColumnTitle) and font (TFont).


TColumn::DefaultAlignment

TColumn	See also

Returns the default alignment for the column.

Classes::TAlignment __fastcall DefaultAlignment(void);

Description

Use DefaultAlignment to determine the alignment of the data in the column when the Alignment property has not been explicitly set. DefaultAlignment returns the Alignmnent of the TField associated with the column. If the column has no dataset field associated with it, DefaultAlignment returns taLeftJustify.


TColumn::DefaultColor

TColumn	See also

Returns the default background color for the column.

Graphics::TColor __fastcall DefaultColor(void);

Description

Use Default color to determine the color of the column when the Color property is not explicitly set. DefaultColor returns the Color of the data grid to which the column belongs. If the column has no associated data grid, DefaultColor returns clWindow.


TColumn::DefaultFont

TColumn	See also

Returns the default font for data displayed in the column.

Graphics::TFont* __fastcall DefaultFont(void);

Description

DefaultFont returns the Font of the data grid to which the column belongs. If the column has no associated data grid, DefaultFont returns the current value of the column’s Font property.


TColumn::DefaultImeMode

TColumn	See also

Describes the default behavior of the Input Method Editor (IME).

Controls::TImeMode __fastcall DefaultImeMode(void);

Description

DefaultImeMode returns the ImeMode property of the data grid to which the column belongs. If the column has no associated data grid, DefaultImeMode returns the current value of the column’s ImeMode property.


TColumn::DefaultImeName

TColumn	See also

Returns the name of the default Input Method Editor (IME).

System::AnsiString __fastcall DefaultImeName();

Description

DefaultImeName returns the ImeName property of the data grid to which the column belongs. If the column has no associated data grid, DefaultImeName returns the current value of the column’s ImeName property.


TColumn::DefaultReadOnly

TColumn	See also

Returns the default ReadOnly setting for the column.

bool __fastcall DefaultReadOnly(void);

Description

Reflects the ReadOnly state of the grid and the grid’s dataset and field.


TColumn::DefaultWidth

TColumn	See also

Returns the default width for the column.

int __fastcall DefaultWidth(void);

Description

The value of DefaultWidth is determined as follows:

•	If the column has no data grid associated with it, DefaultWidth returns 64.

•	If the column has an associated data grid but the Field property is empty, DefaultWidth returns data grid’s protected DefaultColWidth property. Usually, this value is 64.

•	If the column has an associated data field, DefaultWidth is calculated from the TField object’s DisplayWidth property using the column’s font.

•	If the dgTitles flag is set in the data grid’s Options property, DefaultWidth is increased (as necessary) to accommodate the column’s title caption.


TColumn::~TColumn

TColumn	See also

Destroys the column and frees its memory.

__fastcall virtual ~TColumn(void);

Description

Do not call ~TColumn directly. Instead, use the delete keyword on the object, which causes ~TColumn to be invoked automatically.

~TColumn eliminates the TColumn instance along with its title (TColumnTitle), font (TFont), and pick list (TStrings).


TColumn::RestoreDefaults

TColumn	See also

Restores the column’s default settings.

virtual void __fastcall RestoreDefaults(void);

Description

RestoreDefaults reinitializes the AssignedValues, ButtonStyle, Font, and PickList properties, freeing the pick list (TStrings) object if there is one. It also calls the RestoreDefaults method in the column’s title (TColumnTitle) to restore the default properties of the column title.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


 TComboBox

Hierarchy	Properties	Methods	Events	See also

TComboBox combines an edit box with a scrollable list.

Unit

stdctrls

Description

A TComboBox component is an edit box with a scrollable drop-down list attached to it. Users can select an item from the list or type directly into the edit box.


TComboBox properties

TComboBox	Alphabetically	Legend

Derived from TCustomComboBox

Canvas

CharCase

DropDownCount

DroppedDown

ItemHeight

ItemIndex

Items

MaxLength

SelLength

SelStart

SelText

Sorted

Style

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TComboBox properties

TComboBox	By object	Legend

Align

BoundsRect

Brush

Canvas

CharCase

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

DropDownCount

DroppedDown

Enabled

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

ItemHeight

ItemIndex

Items

Left

MaxLength

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

SelLength

SelStart

SelText

ShowHint

Showing

Sorted

Style

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TComboBox events

TComboBox	Alphabetically	Legend

Derived from TCustomComboBox

OnChange

OnDrawItem

OnDropDown

OnMeasureItem

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TComboBox events

TComboBox	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDrawItem

OnDropDown

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMeasureItem

OnStartDrag


TComboBox methods

TComboBox	Alphabetically

In TComboBox

~TComboBox

TComboBox

Derived from TCustomComboBox

Clear

SelectAll

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TComboBox methods

TComboBox	By object

~TComboBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TComboBox

Update

UpdateControlState


TComboBox::TComboBox

TComboBox

TComboBox creates a new TComboBox object.

__fastcall TComboBox(HWND ParentWindow) : Stdctrls::TCustomComboBox(ParentWindow) { }

__fastcall virtual TComboBox(Classes::TComponent* AOwner) : Stdctrls::TCustomComboBox(AOwner) { }

Description

Do not call TComboBox directly. Instead, use the keyword new, which returns an indirect reference to the new combo box. TComboBox objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the combo box with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the combo box in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the combo box is implemented as an ActiveX control.


TComboBox::~TComboBox

TComboBox

~TComboBox frees the memory associated with the TComboBox object.

__fastcall virtual ~TComboBox(void) { }

Description

Do not call ~TComboBox directly. Instead, use the delete keyword on the object, which causes ~TComboBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomComboBox


TComClassManager

Hierarchy	Methods	See also

TComClassManager is the class type of the ComClassManager variable in the ComObj unit.

Unit

comobj

Description

An instance of TComClassManager is returned by the ComClassManager function in the ComObj unit. This instance of TComClassManager manages the class factory objects owned by COM servers.

For all servers linked to the module containing this unit, the manager returned by ComClassManager maintains a list of pointers to the class factory objects. This list is updated by the individual COM servers, which add class factories objects when they are created and delete them when they are destroyed. The ComClass manager has methods that are used to manipulate class factories based upon their associated servers. These methods process iterative actions on factories or return factories based upon the class object type they create.


TComClassManager methods

TComClassManager	Alphabetically

In TComClassManager

~TComClassManager

ForEachFactory

GetFactoryFromClass

GetFactoryFromClassID

TComClassManager

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComClassManager methods

TComClassManager	By object

~TComClassManager

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

ForEachFactory

Free

FreeInstance

GetFactoryFromClass

GetFactoryFromClassID

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TComClassManager


TComClassManager::ForEachFactory

TComClassManager	See also

Processes iterative actions on factories associated with a given server.

void __fastcall ForEachFactory(TComServerObject* ComServer, TFactoryProc &FactoryProc);

Description

ForEachFactory is used to process an action, specified by the FactoryProc parameter, on all class factories in the factory list that are owned by the ComServer specified by the ComServer parameter.

ForEachFactory is used internally by the COM server to:

•	Destroy factories when the associated COM server unloads.

•	Have factories register their class objects in the system registry, when the associated COM server initializes.

•	Have the factories update the system registry when necessary.

TFactoryProc is the method-pointer type of the FactoryProc parameter of ForEachProperty. TFactoryProc defines a method that takes a class factory as a parameter.


TComClassManager::GetFactoryFromClass

TComClassManager	See also

Returns the class factory for a given COM class.

TComObjectFactory* __fastcall GetFactoryFromClass(System::TMetaClass* ComClass);

Description

GetFactoryFromClass is used internally by C++Builder to obtain the correct class factory in order to create instances of a specified COM object.

GetFactoryFromClass returns the class factory associated with the COM class specified by the ComClass parameter. If no such class factory is found in the list maintained by the ComClass manager, an EOleError exception is raised indicating that the class factory for the specifed COM class is not in the current list.


TComClassManager::GetFactoryFromClassID

TComClassManager

Returns the class factory for a given COM class identifier.

TComObjectFactory* __fastcall GetFactoryFromClassID(const GUID &ClassID);

Description

GetFactoryFromClassID is used internally by DllGetClassObject to obtain a reference to the IClassFactory interface of the corresponding class factory object for a given class object specified by the ClassID parameter.

GetFactoryFromClassID returns the class factory associated with the COM class specified by the ClassID parameter. If the class cannot be found, GetFactoryFromClassID returns NULL.


TComClassManager::TComClassManager

TComClassManager

TComClassManager creates a new TComClassManager object.

__fastcall TComClassManager(void) : System::TObject() { }


TComClassManager::~TComClassManager

TComClassManager

~TComClassManager frees the memory associated with the TComClassManager object. Do not call ~TComClassManager directly. Instead, use the delete keyword on the object, which causes ~TComClassManager to be invoked automatically.

__fastcall virtual ~TComClassManager(void) { }


Hierarchy

TObject


TCommonDialog

Hierarchy	Properties	Methods	Events	See also

TCommonDialog is the ancestor of all components that represent Windows common dialog boxes.

Unit

dialogs

Description

TCommonDialog is an abstract class that represents Windows common dialog boxes. Its descendants handle such tasks as finding and opening files, setting fonts and colors, and printing. The dialogs do not appear at runtime until activated by a call to the Execute method. Except for TFindDialog and TReplaceDialog, these dialogs are all modal.

The TCommonDialog descendants are nonvisual components that generate a single function call to COMMDLG.DLL, and are therefore less easily modified than other C++Builder components. New components that encapsulate common-dialog functions should descend from TCommonDialog. Most other dialog boxes should descend from TForm.


TCommonDialog properties

TCommonDialog	Alphabetically	Legend

In TCommonDialog

Ctl3D

Handle

HelpContext

Template

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCommonDialog properties

TCommonDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DesignInfo

Handle

HelpContext

Name

Owner

Tag

Template

VCLComObject


TCommonDialog::Ctl3D

TCommonDialog	See also

Determines whether the dialog has a three-dimensional look.

__property bool Ctl3D = {read=FCtl3D, write=FCtl3D, default=1};

Description

If Ctl3D is set to true, the dialog box and the controls in it appear three-dimensional. If Ctl3D is set to false, the dialog and its controls appear flat.

Note

For dialogs to appear three-dimensional under Windows NT 3.51, CTL3D32.DLL must be installed in the System32 directory.


TCommonDialog::Handle

TCommonDialog	See also

Specifies the window handle of the dialog.

__property HWND Handle = {read=FHandle, nodefault};

Description

The Handle property, which provides access to the dialog’s window handle after a call to Execute, can be used in OnShow and OnClose event handlers. Handle is reset to 0 after the dialog closes.


TCommonDialog::HelpContext

TCommonDialog	See also

Specifies the context number for online Help.

__property Classes::THelpContext HelpContext = {read=FHelpContext, write=FHelpContext, default=0};

Description

The HelpContext property is an integer value that determines which Help screen appears when the user requests context-sensitive online Help. If HelpContext is set to the default value of 0, the dialog inherits the Help context of its parent.


TCommonDialog::Template

TCommonDialog	See also

Points to a custom template for the dialog.

__property char * Template = {read=FTemplate, write=FTemplate};

Description

Template points to a resource identifier (a null-terminated string or an integer created with MAKEINTRESOURCE) that identifies a Windows dialog resource in the current HInstance module. The Execute method uses this resource to customize the appearance of the dialog.

For example, if 123 is an integer identifier in the resource file MYDLG.RES, the following code could be used customize OpenDialog1.

#pragma resource "Mydlg.res"

OpenDialog1->Template = MakeIntResource(123);

If DialogA is a string identifier in MYDLG.RES, then the following code could be used customize PrintDialog1.

#pragma resource "Mydlg.res"

PrintDialog1->Template = "DialogA";


TCommonDialog events

TCommonDialog	Alphabetically	Legend

In TCommonDialog

OnClose

OnShow


TCommonDialog events

TCommonDialog	By object	Legend

OnClose

OnShow


TCommonDialog::OnClose

TCommonDialog	See also

Occurs when the dialog closes.

__property Classes::TNotifyEvent OnClose = {read=FOnClose, write=FOnClose};

Description

Write an OnClose event handler to perform special processing when the dialog closes.


TCommonDialog::OnShow

TCommonDialog	See also

Occurs when the dialog opens.

__property Classes::TNotifyEvent OnShow = {read=FOnShow, write=FOnShow};

Description

Write an OnShow event handler to perform special processing when the dialog is displayed.


TCommonDialog methods

TCommonDialog	Alphabetically	Legend

In TCommonDialog

~TCommonDialog

Execute

TCommonDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCommonDialog methods

TCommonDialog	By object	Legend

~TCommonDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TCommonDialog


TCommonDialog::TCommonDialog

TCommonDialog	See also

Creates and initializes a TCommonDialog instance.

__fastcall virtual TCommonDialog(Classes::TComponent* AOwner);

Description

Do not instantiate a TCommonDialog object. To add a common dialog to a form, create an instance of a TCommonDialog descendant using the new keyword.

TCommonDialog calls the parent object's constructor method and initializes the Ctl3D property to true.


TCommonDialog::~TCommonDialog

TCommonDialog	See also

Destroys the TCommonDialog instance and frees its memory.

__fastcall virtual ~TCommonDialog(void);

Description

Do not call ~TCommonDialog directly. Instead, use the delete keyword on the object, which causes ~TCommonDialog to be invoked automatically.


TCommonDialog::Execute

TCommonDialog

Displays the dialog box.

virtual bool __fastcall Execute(void) = 0;

Description

TCommonDialog introduces the abstract Execute method, which descendant classes use to open the dialog instance at runtime. Generally, Execute returns true when the user makes a selection and clicks OK, and returns false when the user closes the dialog without making a selection.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


TComObjectFactory

Hierarchy	Properties	Methods	See also

TComObjectFactory is the type of the class factory object used to instantiate a TComObject class.

Unit

comobj

Description

TComObjectFactory supports the IUknown, IClassFactory, and IClassFactory2 interfaces. The IClassFactory interface is implemented by class objects associated with class identifiers (CLSIDs) for the classes that they instantiate. IClassFactory must be implemented for every object definition, so that objects of that type can be created. The IClassFactory2 interface is implemented by class factories for classes that need support for licensing.

Class factories instantiate the COM classes specified by a registered class identifier (CLSID). Class factory objects are created automatically by the COM servers that contain the code for the class objects and their associated classes. When a class factory is created, the CLSID is specified in a parameter to the constructor of the class factory object. This CLSID indicates the type of object for which the class factory creates instances.

Class factory objects can also be externally instantiated by directly calling the Windows API function CoCreateClassObject. The functions CreateComObject or CreateOleObject can also be called to instantiate a COM class. These functions indirectly use class factories to instantiate the classes. When creating multiple instances of a class that has a CLSID, however, it is more efficient to instantiate a class factory, obtain a pointer to it’s IClassFactory interface, and use its methods as needed.

Class factories are managed on the server by a global class manager accessed using the ComClassManager function. This class manager maintains a list of class factories through which the factories are manipulated, ususally according to the COM server that owns them.

Interfaces implemented

IUnknown, IClassfactory, IClassFactory2


TComObjectFactory properties

TComObjectFactory	Alphabetically	Legend

In TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

ShowErrors

SupportsLicensing


TComObjectFactory properties

TComObjectFactory	By object	Legend

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

ShowErrors

SupportsLicensing


TComObjectFactory::ClassID

TComObjectFactory	See also

Specifies the class identifier (CLSID) for the COM class that the particular instance of the factory can instantiate.

__property GUID ClassID = {read=FClassID};

Description

ClassID is used to identify the COM class that the factory can instantiate for this factory instance. It is as a used by other methods to identify this class.

ClassID is initialized, in the class factory constructor, to the CLSID that is passed to the constructor. ClassID is also used in the UpdateRegistry method when the COM server’s initialize is called.


TComObjectFactory::ClassName

TComObjectFactory	See also

Specifies the name of the class that the class factory instantiates.

__property System::AnsiString ClassName = {read=FClassName};

Description

ClassName is the name identifying the COM class that the class factory instantiates.

ClassName is initialized, in the class factory constructor, to the class name that is passed to the constructor.


TComObjectFactory::ComClass

TComObjectFactory	See also

Specifies the class type that the factory instantiates.

__property System::TMetaClass* ComClass = {read=FComClass};

Description

ComClass is used by the class manager’s GetFactoryFromClass method. This method checks the ComClass of each class factory on the server, against the class passed to it, in order to return the class factory that creates objects of that type. It is also used by the CreateComObject method to create the correct COM class.

ComClass is initialized, in the class factory constructor, to the COM class type that is passed to the constructor.


TComObjectFactory::ComServer

TComObjectFactory	See also

Specifies the COM server that owns the class factory.

__property TComServerObject* ComServer = {read=FComServer};

Description

ComServer indicates the COM server that contains the class factory object. It is used by the class manager methods to process actions on specific factories based upon which server owns them.

The class manager’s ForEachFactory is a general purpose method that uses ComServer to check the sever ComServer of each factory in the class manager’s factory list. ForEachFactory then calls the factory procedure passed as a parameter to it, for each of the factories of that particular COM server.

ComServer is also used in the COM class’s CreateFromFactory constructor to call the COM server’s CountObject method. This increments the object count on the server when the class factory instantitates its class type.

ComServer is initialized, in the class factory constructor, to the server that is passed to its constructor.


TComObjectFactory::Description

TComObjectFactory	See also

Describes the class object.

__property System::AnsiString Description = {read=FDescription};

Description

Description is used in the registration database, when the class factory is registered, to describe the class object.

Description is initialized, in the class factory constructor, to the Description parameter that is passed to the constructor. This description is retrieved from the type library.


TComObjectFactory::ErrorIID

TComObjectFactory	See also

Indicates the interface of the CoClass in which an error occurred.

__property GUID ErrorIID = {read=FErrorIID, write=FErrorIID};

Description

Use ErrorIID to determine the interface in which an error occurred.  For most CoClasses this will be the primary interface for that CoClass, as indicated in the type library.


TComObjectFactory::Instancing

TComObjectFactory	See also

Indicates how the COM class is created.

__property TClassInstancing Instancing = {read=FInstancing, nodefault};

Description

Instancing indicates whether the object that the factory instantiates is created internal to the COM server module, or in single or multiple instances.

Instancing is initialized, in the class factory constructor, to the Instancing parameter that is passed to the constructor.

TClassInstancing is the type of the Instancing property. The following table lists the possible values of the TClassInstancing type:

Value	Meaning

ciInternal	The COM object is created internal to the COM server.

ciSingleInstance	The COM object is created as a single instance.

ciMultiInstance	The COM object is created as one of multiple instances.


TComObjectFactory::LicString

TComObjectFactory

Contains licensing information about the object.

__property System::WideString LicString = {read=FLicString, write=FLicString};

Description

LicString is used to validate whether or not the user has valid access to the object for development. LicString can be any string defined by the developer who is optionally licensing the object.


TComObjectFactory::ProgID

TComObjectFactory	See also

Specifies the name of the class factory.

__property System::AnsiString ProgID = {read=GetProgID};

Description

ProgID is the programmatic identifier that specifies the vendor, component, and version of the class factory object.

Every object class that can be inserted into an OLE container has ProgID.


TComObjectFactory::ShowErrors

TComObjectFactory

Indicates whether the COM object factory displays a message box when exceptions are raised.

__property bool ShowErrors = {read=FShowErrors, write=FShowErrors, nodefault};

Description

When ShowErrors is true, exceptions that are raised when trying to create a COM object are caught and a message box is displayed to describe the error. When ShowErrors is false, the exception is not caught by the COM object factory.


TComObjectFactory::SupportsLicensing

TComObjectFactory

Indicates whether or not the object being instantiated supports licensing.

__property bool SupportsLicensing = {read=FSupportsLicensing, write=FSupportsLicensing, nodefault};

Description

SupportsLicensing is used to determine whether a user has valid access to the object.


TComObjectFactory methods

TComObjectFactory	Alphabetically

In TComObjectFactory

~TComObjectFactory

CreateComObject

RegisterClassObject

TComObjectFactory

UpdateRegistry

Derived from TObject

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComObjectFactory methods

TComObjectFactory	By object

~TComObjectFactory

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComObject

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

SafeCallException

TComObjectFactory

UpdateRegistry


TComObjectFactory::TComObjectFactory

TComObjectFactory	See also

Instantiates a class factory object.

TComObjectFactory* FNext;

Description

TComObjectFactory instantiates a class factory, usually when the server is loaded. Class factories should be instantiated in the initialization section of the unit that includes their associated server, so that they are automatically available when the server is loaded.

TComObjectFactory allocates memory for a class factory object, and adds the object to the class factory list managed by the ComClassManager. Then TComObjectFactory initializes the following properties with values passed to it:

•	Sets ComServer to the ComServer parameter.

•	Sets ComClass to the ComClass parameter.

•	Sets ClassID to the ClassID parameter.

•	Sets ClassName to the ClassName parameter.

•	Sets Description to the Description parameter.

•	Sets Instancing to the Instancing parameter.

•	Sets ErrorIID to IUnknown.


TComObjectFactory::TComObjectFactory
TComObjectFactory::CreateComObject

TComObjectFactory	See also

Instantiates a TComObject object.

virtual TComObject* __fastcall CreateComObject(const _di_IUnknown Controller);

Description

CreateComObject is the method that instantiates the class type for which TComObjectFactory is the class factory. CreateComObject calls the CreateFromFactory constructor of the TComObject class to create a COM object. CreateComObject passes itself as the Factory parameter to CreateFromFactory.

CreateComClass creates a COM object based upon the value of the ComClass property. ComClass is the class identifier (CLSID) used by other applications to identify the COM class for which they request an object instance.


TComObjectFactory::~TComObjectFactory

TComObjectFactory	See also

Disposes of an instance of a class factory.

__fastcall virtual ~TComObjectFactory(void);

Description

Do not call ~TComObjectFactory directly. Instead use the delete keyword on the object, which causes ~TComObjectFactory to be invoked automatically.

Class factories are automatically destroyed when their corresponding servers are unloaded.


TComObjectFactory::RegisterClassObject

TComObjectFactory

Registers the COM class associated with the factory object.

void __fastcall RegisterClassObject(void);

Description

RegisterClassObject registers an EXE class object with OLE so other applications can connect to it. EXE object applications should call RegisterClassObject on startup. It can also be used to register internal objects for use by the same EXE or other code (such as DLLs) that the EXE uses.

If RegisterClassObject is not successful, an EOleSysError is raised with the following error code possibilites:

Value	Meaning

E_INVALIDARG	One or more the arguments are invalid.

E_OUTOFMEMORY	Not enough memory.

E_UNEXPECTED	An unexpected error occurred.

CO_E_OBJISREG 	The class was already registered in the class object table.

Only EXE object applications call RegisterClassObject. Object handlers or DLL object applications do not call this function. Instead, they must implement and export the DllGetClassObject function.

At startup, a multiple-use EXE object application must create a class object (with the IClassFactory interface on it), and call RegisterClassObject to register the class object. Object applications that support several different classes (such as multiple types of embeddable objects) must allocate and register a different class object for each.

Multiple registrations of the same class object are independent and do not produce an error. Each subsequent registration yields a unique key.


TComObjectFactory::UpdateRegistry

TComObjectFactory	See also

Registers COM objects created by the factory.

virtual void __fastcall UpdateRegistry(bool Register);

Description

UpdateRegistry is called for EXEs when the EXE is run, and for DLLs or EXEs when the routines are called to specifically register or unregister the server.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject


TComObject

Hierarchy	Properties	Methods	See also

TComObject is the base class for creating simple COM classes, such as those used for creating Shell extensions.

Unit

comobj

Description

TComObject is a COM object that supports the IUnknown and ISupportErrorInfo interfaces. TComObject provides the implementation for simple COM objects that have:

•	A class identifier (CLSID) for external instantiation using a class factory.

•	Otional support for aggregation implemented through by the IUknown methods.

•	Support for the SafeCall calling convention and OLE exception-handling by implementing IProvideErrorInfo.

•	Support for the the IErrorInfo mechanism.

TComObject can be used as a base class for creating classes for COM objects that must have a class identifier (CLSID). CLSIDs are used to register the class in the database registry and to externally instantiate the class using class factory. The class factory for TComObject is TComObjectFactory. The class factory properties provide information about TComObject class, such as its name, description, CLSID, and so on. The TComObjectFactory methods are used to register the TComObject class in the registry and to instantiate it.

TComObject can be instantiated either as a single COM object, or as part of an aggregate. The IUnknown methods are implemented in TComObject to support aggregation by appropriately delegating to the controlling IUnknown interface when the instantiated COM object is the inner object of an aggregate. Consequently, for all interfaces that are implemented by the inner COM object, its reference count will not be directly affected when an interface reference is created.

TComObject supports the ISupportErrorInfo interface which allows OLE Automation controllers to query whether an error object will be available, and ensures that error information can be propagated correctly up the call chain. By implementing the ISupportErrorInfo interface method, InterfaceSupportsErrorInfo, TComObject supports the IErrorInfo mechanism, thereby providing support for OLE exception-handling and the safecall calling convention. The information available through the IErrorInfo interface is used for SafeCall error handling.

Using TComObject will not require the instantiated object to have a type library.

Implemented methods of ISupportErrorInfo

InterfaceSupportsErrorInfo method


TComObject properties

TComObject	Alphabetically	Legend

In TComObject

Controller

Factory

RefCount


TComObject properties

TComObject	By object	Legend

Controller

Factory

RefCount


TComObject::Controller

TComObject	See also

Specifies the controlling IUnknown interface that controls interfaces within an aggregate object.

__property _di_IUnknown Controller = {read=GetController};

Description

Controller is the controlling IUnknown interface for the inner object in an aggregate. The QueryInterface, AddRef, and Release methods of all other interfaces of the inner object (except IUnknown) must delegate to the controlling IUnknown. Because of this delegation, the inner object’s reference count is not affected when these methods are called.

Controller is NULL if the object is not part of an aggregate. If Controller is non-NULL, the object is part of an aggregate, and Controller is the controlling interface.


TComObject::Factory

TComObject	See also

Specifies the class factory object for the TComObject class.

__property TComObjectFactory* Factory = {read=FFactory};

Description

Factory is the class factory which is used to instantiate a TComObject.


TComObject::RefCount

TComObject	See also

Indicates the number of references to the COM object that are currently in use.

__property int RefCount = {read=FRefCount, nodefault};

Description

RefCount is used to determine when the object can be destroyed. RefCount is the number of references to interfaces implemented by the COM object. When RefCount is zero, the object can be is destroyed.

RefCount is automatically incremented when references to interfaces implemented by the COM object are created, and is automatically decremented when those references are destroyed. RefCount is usually incremented by the IUnknown AddRef method and decremented by the IUnknown method, Release.

RefCount can be artifically incremented when a new object is created which may be passed as a function parameter. In this case, RefCount should not be zero, and should be incremented prior to the function call and decremented when the function returns. If you pass a class factory to the constructor as the first parameter, the constructor artifically increments and decrements RefCount for this reason.


TComObject methods

TComObject	Alphabetically

In TComObject

~TComObject

Initialize

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

TComObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TComObject methods

TComObject	By object

~TComObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

Initialize

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

TComObject


TComObject::TComObject

TComObject	See also

Instantiates a COM object that is not part of an aggregate.

__fastcall TComObject(void);

__fastcall TComObject(_di_IUnknown const Controller);

__fastcall TComObject(TComObjectFactory* Factory, _di_IUnknown const Controller);

Description

TComObject creates a new TComObject object.

To create a COM object that is not part of an aggregate, call TComObject without any parameters.

To create a COM object that is part of an aggregate, call TComObject with the IUnknown control object as the Controller parameter.

To create a COM object from a class factory, call TComObject with the class factory as the Factory parameter and the IUnknown control object as the Controller parameter.

TComObject allocates memory for a COM object, and then initializes the following properties:

•	Sets RefCount to 1, as a means of artificial reference counting in the case that the newly created object has a zero reference count and is passed as a parameter.

•	Sets Factory to the Factory parameter (if specified), which is the instance of the class factory responsible for creating the object.

•	Sets Controller to the Controller parameter (if specified), which is either a control object, if the object is part of an aggregate, or NULL if it is not.

•	Calls on the COM server to increment the reference count of objects dependent on it.

•	Calls Initialize.

•	Decrements the RefCount that was artificially incremented.


TComObject::~TComObject
 KTComObject::~TComObject

TComObject	See also

Disposes of an instance of a COM object.

__fastcall virtual ~TComObject(void);

Description

Do not call ~TComObject directly. Instead, use the delete keyword on the object, which causes ~TComObject to be invoked automatically.

~TComObject checks to see if the Factory property is NULL. If it is NULL, then ~TComObject passes false to the CountObject method of the Factory object’s ComServer, allowing the DLL (server) to be unloaded if no more objects are dependent upon the server.


TComObject::Initialize

TComObject	See also

Provides an interface to a method that initializes the COM object.

virtual void __fastcall Initialize(void);

Description

Initialize currently does nothing. Descendant COM objects can override Initialize.


TComObject::ObjAddRef

TComObject

Implements the AddRef method of the IUnknown interface.

virtual int __stdcall ObjAddRef(void);

Description

QueryInterface is used as the implementation of the IUnknown QueryInterface method when the COM object (TComObject) is not part of an aggregate.


TComObject::ObjQueryInterface

TComObject

Implements the QueryInterface method of the IUnknown interface.

virtual HRESULT __stdcall ObjQueryInterface(const GUID &IID, void *Obj);

Description

QueryInterface queries whether the COM object supports a given interface specified by the IID parameter. QueryInterface is used as the implementation of the IUnknown QueryInterface method when the COM object (TComObject) is not part of an aggregate.


TComObject::ObjRelease

TComObject

Implements the Release method of the IUnknown interface.

virtual int __stdcall ObjRelease(void);

Description

QueryInterface is used as the implementation of the IUnknown QueryInterface method when the COM object (TComObject) is not part of an aggregate.


TComObject::SafeCallException

TComObject

Handles OLE exceptions.

virtual HRESULT __fastcall SafeCallException(System::TObject* ExceptObject, void * ExceptAddr);

Description

SafeCallException prevents an exception from being raised to escape its scope. Any exceptions raised must also be handled within the method.

The implementation of a safecall method guarantees that no exceptions are raised by enclosing the statement part of the method in an implied try…catch block.

Note:	SafeCallException calls the global routine HandleSafeCallException, which provides a standard way of handling this behavior. Methods of a CoClass that supports OLE exception handling (that implements the ISupportErrorInfo interface) are affected by this function. If those CoClass methods use the safecall calling convention, they are modified to return an HRESULT. Procedures will return an HRESULT, and functions will pass their usual result value as the last (out) parameter, and will return an HRESULT instead. The method is enclosed in a try…finally block, after which the HRESULT is returned, and the environment is set up so that the ISupportErrorInfo implementation will work correctly.


Accessibility

Read-only


Hierarchy

TObject


TComponentEditor

Hierarchy	Properties	Methods	See also

TComponentEditor is the base class for all component editors.

Unit

dsgnintf

Description

Use TComponentEditor or one of its descendants as a base class when defining a design-time editor for working with a new component class. Create a new component editor class for a component class to add verbs to its context menu, change its default double-click behavior, or allow the component to use a new clipboard format.

Once the component editor is defined, it can be registered to work with a particular component class.  A registered component editor is created for each component of that class when it is selected in the form designer.  When the component is double-clicked, the Edit method of the component editor is called.  When the user right-clicks the component, the GetVerbCount and GetVerb methods of the editor are called to build context menu. To create the association between a component editor and a component class, call RegisterComponentEditor.

C++Builder provides a descendant of TComponentEditor (TDefaultEditor) which all components use if they have no registered association with a component editor.


TComponentEditor properties

TComponentEditor	Alphabetically 	Legend

In TComponentEditor

Component

Designer


TComponentEditor properties

TComponentEditor	By object 	Legend

Component

Designer


TComponentEditor::Component

TComponentEditor 	See also 	Example

Provides access to the component in the form designer that uses this component editor.

__property Classes::TComponent* Component = {read=FComponent};

Description

Use Component to read from and make changes to the component associated with the component editor. A component editor is created for each instance of the registered component class when it is selected in the form designer.  Component is the selected instance.

Note:	When the component editor makes changes to the component, it must call the Modified method of the form designer that is specified by the Designer property.


 TComponentEditor::Designer

TComponentEditor	See also

Provides access to the form designer object in the IDE.

__property TFormDesigner* Designer = {read=FDesigner};

Description

Use Designer to read from or make changes to the current form or module in the IDE. The form designer has methods that can access the components in the current .CPP file and other components defined in included header files, create or alter the methods in the current .CPP file, and so on.

Note:	When the component editor makes changes to the component, it must call the Modified method of the form designer.


TComponentEditor methods

TComponentEditor	Alphabetically

In TComponentEditor

~TComponentEditor

Copy

Edit

ExecuteVerb

GetVerb

GetVerbCount

TComponentEditor

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComponentEditor methods

TComponentEditor	By object

~TComponentEditor

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Copy

DefaultHandler

Dispatch

Edit

ExecuteVerb

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetVerb

GetVerbCount

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TComponentEditor


TComponentEditor::Copy

TComponentEditor	See also 	Example

Provides an opportunity to copy the component to the clipboard in custom formats.

virtual void __fastcall Copy(void);

Description

Do not call the Copy method.  It is called automatically when the user copies the component to the clipboard.  When Copy is called, the component's filed image is already on the Clipboard. Override Copy to copy a different clipboard format, which is ignored by the designer but might be recognized by another application.


TComponentEditor::TComponentEditor

TComponentEditor	See also

Instantiates a component editor.

__fastcall virtual TComponentEditor(Classes::TComponent* AComponent, TFormDesigner* ADesigner);

Description

Do not call the TComponentEditor constructor.  It is called automatically by the form designer to generate an instance of the component editor for a selected component. AComponent is the selected component on which the editor will operate.  ADesigner is the form designer, which can be used to obtain information about the components and methods in the designer and to create or manipulate components and methods.


TComponentEditor::Edit

TComponentEditor	See also

Responds when the user double-clicks the component in the form designer.

virtual void __fastcall Edit(void);

Description

The Object Inspector calls Edit when the user double-clicks the component. Edit executes the first verb supplied by the component editor.  That is, if GetVerbCount returns a value greater than zero, Edit calls

ExecuteVerb(0);

Override the Edit method to implement another response when the user double-clicks the component.  For example, the Edit method can bring up a dialog or design expert.


TComponentEditor::ExecuteVerb

TComponentEditor	See also

Performs the action of a specified verb.

virtual void __fastcall ExecuteVerb(int Index);

Description

The form designer calls ExecuteVerb when the user selects the verb that is returned by GetVerb(Index).  This verb is the string that appears in the corresponding position of the component’s context menu.

TComponentEditor does not supply any verbs for its component.  As a result, ExecuteVerb does nothing.  Override GetVerb to provide a set of verbs, or menu strings, that are added to the context menu which appears when the user right-clicks the component.  Override ExecuteVerb to implement a response to each of these verbs.


TComponentEditor::GetVerb

TComponentEditor	See also

Returns the string that corresponds to the specified position of the component’s context menu.

virtual System::AnsiString __fastcall GetVerb(int Index);

Description

The form designer calls GetVerb iteratively to build the context menu that appears when the user right-clicks the component.

When overriding GetVerb, adding an ampersand (&) to a verb will cause the following character to appear underlined in the context menu and to act as a shortcut key for selecting the menu item.  Be sure to add ellipses (...) to the end of a verb if its corresponding action is to bring up a dialog.


TComponentEditor::GetVerbCount

TComponentEditor	See also

Returns the number of menu strings added to the context menu by the component editor.

virtual int __fastcall GetVerbCount(void);

Description

The form designer calls GetVerbCount when the user right-clicks the component in order to determine the number of menu items that should be added to the context menu.  It then adds the menu items by calling GetVerb for every value from 0 to GetVerbCount - 1.

TComponentEditor does not supply any verbs for its component.  As a result, GetVerbCount returns 0.  Override GetVerbCount when providing a set of verbs, or menu strings, to be added to the context menu.  When overriding GetVerbCount, override GetVerb to return the actual strings, and override ExecuteVerb to implement a response to each of these verbs.  For example, if adding two verbs to the context menu, GetVerbCount should return 2, GetVerb should return a value for an Index of 0 and for an Index of 1, and ExecuteVerb should perform the corresponding actions for an Index of 0 and for an Index of 1.


TComponentEditor::~TComponentEditor

TComponentEditor

Frees the memory associated with the TComponentEditor object.

__fastcall virtual ~TComponentEditor(void) { }

Description

Do not call ~TComponentEditor . The form designer handles the creation and destruction of the component editor when objects are selected and unselected in the IDE.


Accessibility

Read-only


Hierarchy

TObject


TComponentFactory

Hierarchy	Properties	Methods

TComponentFactory is the class factory for creating instances of C++Builder components that support interfaces.

Unit

vclcom

Description

TComponentFactory creates instances of component classes that implement interfaces. TComponentFactory inherits support for the IClassFactory and IClassFactory2 interfaces.

Note

These components are actually created as contained objects of an automation object (aggregate).


TComponentFactory properties

TComponentFactory	Alphabetically	Legend

Derived from TAutoObjectFactory

DispIntfEntry

DispTypeInfo

Derived from TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TComponentFactory properties

TComponentFactory	By object	Legend

ClassID

ClassName

ComClass

ComServer

Description

DispIntfEntry

DispTypeInfo

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TComponentFactory methods

TComponentFactory	Alphabetically

In TComponentFactory

~TComponentFactory

TComponentFactory

Derived from TAutoObjectFactory

GetIntfEntry

Derived from TTypedComObjectFactory

ClassInfo

GetInterfaceTypeInfo

UpdateRegistry

Derived from TComObjectFactory

CreateComObject

RegisterClassObject

Derived from TObject

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComponentFactory methods

TComponentFactory	By object

~TComponentFactory

ClassInfo

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComObject

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetInterfaceTypeInfo

GetIntfEntry

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

SafeCallException

TComponentFactory

UpdateRegistry


TComponentFactory::TComponentFactory

TComponentFactory	See also

TComponentFactory instantiates an instance of a TComponentFactory object.

__fastcall TComponentFactory(Comobj::TComServerObject* ComServer, System::TMetaClass* ComponentClass, const GUID &ClassID, Comobj::TClassInstancing Instancing);

Description

TComponentFactory allocates memory for a TComponentFactory object, and calls the parent object's constructor, passing its parameters in the same order. The ComponentClass parameter is passed cast as a TAutoClass and passed to the AutoClass parameter.


TComponentFactory::~TComponentFactory

TComponentFactory

~TComponentFactory frees the memory associated with the TComponentFactory object. Do not call ~TComponentFactory directly. Instead, use the delete keyword on the object, which causes ~TComponentFactory to be invoked automatically.

__fastcall virtual ~TComponentFactory(void) { }


Accessibility

Read-only


Hierarchy

TObject

TComObjectFactory

TTypedComObjectFactory

TAutoObjectFactory


TComponentFactory example

TComponentFactory


TComponentList

Hierarchy	Properties	Methods	See also

TComponentList maintains a list of persistent objects.

Unit

Dsgnintf

Description

The form designer and its property editors and component editors use TComponentList to manage lists of persistent objects in the IDE. For example, TFormDesigner uses a TComponentList to represent the set of components currently selected in the form designer.  TComponentList introduces properties and methods to

•	Add objects to the list.

•	Compare two lists of objects.

•	Access individual objects in the list.

Note:	TComponentList does not allow objects to be rearranged or deleted from the list once they are added. To maintain a list of objects that allows the objects to be rearranged or deleted, use the TList object, or the Objects property of a descendant of TStrings.


TComponentList properties

TComponentList	Alphabetically	Legend

In TComponentList

Count

Items


TComponentList properties

TComponentList	By object	Legend

Count

Items


TComponentList::Count

TComponentList	See also

Indicates the number of entries in the component list.

__property int Count = {read=GetCount, nodefault};

Description

Read Count to determine the number of entries in the Items array.  Use Count as an upper limit when iterating over all the components in the list.

Count is a read-only property.  To increase the number of components in the list, use the Add method.  Components can not be removed from the list once they have been added.


 TComponentList::Items

TComponentList	See also

Provides indexed access to the objects in the list.

__property Classes::TPersistent* Items[int Index] = {read=Get};

Description

Use Items to access a specific object in the array. The Index parameter indicates the index of the object, where 0 is the index of the first object, 1 is the index of the second object, and so on. Use Items with the Count property to iterate through all of the objects in the list.

To add objects to the Items array, use the Add method.  Once objects have been added, they can’t be deleted or rearranged.


TComponentList methods

TComponentList	Alphabetically

In TComponentList

~TComponentList

Add

Equals

TComponentList

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComponentList methods

TComponentList	By object

~TComponentList

Add

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Equals

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TComponentList


 TComponentList.Add

TComponentList	See also

Adds a new object to the end of the list.

int __fastcall Add(Classes::TPersistent* Item);

Description

Call Add to insert a new object at the end of the Items array. Add returns the index of the new item, where the first item in the list has an index of 0. Add increases the value of Count to reflect the addition of a new object.


 TComponentList::TComponentList

TComponentList	See also

Creates an instance of TComponentList.

__fastcall TComponentList(void);

Description

Do not use the TComponentList constructor directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated component list. After creating the list, use the Add method to add objects to the list.


TComponentList::~TComponentList

TComponentList	See also

Destroys an instance of TComponentList.

__fastcall virtual ~TComponentList(void);

Description

Do not call ~TComponentList directly in an application. Instead, use the delete keyword which takes an indirect reference to the component list.


TComponentList::Equals

TComponentList	See also

Indicates whether the component list is identical to another component list.

bool __fastcall Equals(TComponentList* List);

Description

Call Equals to determine whether the component list specified by the List parameter contains exactly the same objects in the same order as this component list. Equals returns false if the other list

•	Contains objects not in the Items array.

•	Contains a subset of the objects in the Items array.

•	Contains the same objects but in a different order.


Accessibility

Read-only


Hierarchy

TObject


TComServer

Hierarchy	Properties	Methods	Events	See also

TComServer is the class type of the ComServ variable that is declared and instantiated in the ComServ unit.

Unit

comserv

Description

TComServer is the class type used for a COM server, which is a module that contains COM or OLE class defintions. That module that can be either an in-process server (DLL) or a local server (EXE).

TComServer properties contain all necessary information about the server, such as its type library, name, Help file, and so on. They also indicate when and how the server should be loaded and unloaded.

TComServer methods are used

•	As accessor functions for its properties.

•	To create associated class factories to instantiate the COM and OLE classes based upon their class identifier (CLSID).

•	To update the registry database with information about the COM and OLE classes.

TComServer is the type of the ComServ variable that is automatically instantiated in the ComServ unit. Each module that is created as a server for COM objects has its own instance of ComServ.

To manage its class factories the ComServer uses a TComClassManager object, which is accessed using the ComClassManager function in the ComObj unit. The class factories are used primarily by calls to TComClassManager methods.

Note:	The ComServ unit declares and implements global routines that must be exported by each in-process server. These routines automatically handle the registering, unregistering and unloading of the COM server.


TComServer properties

TComServer	Alphabetically	Legend

In TComServer

HelpFileName

IsInprocServer

ObjectCount

ServerFileName

ServerKey

ServerName

StartMode

TypeLib


TComServer properties

TComServer	By object	Legend

HelpFileName

IsInprocServer

ObjectCount

ServerFileName

ServerKey

ServerName

StartMode

TypeLib


TComServer::HelpFileName

TComServer

Specifies the name of the Help file associated with the module.

Description

Use HelpFileName to find the name of the Help file used for the COM server.


TComServer::IsInprocServer

TComServer	See also

Indicates whether the COM server is an in-process server.

Description

InProcServer indicates whether the COM server is an in-process server, meaning that it is running the same process space as the object’s container. The value of this property is set in the COM server’s constructor and is determined by the IsLibrary variable.

C++Builder assumes that all OLE automation servers in DLLs are in-process servers, and that those in applications are not.


TComServer::ObjectCount

TComServer	See also

Indicates how many objects are currently dependent upon the server being loaded.

Description

ObjectCount indicates when the server can be unloaded. ObjectCount contains the number of objects that are currently dependent upon the server.

ObjectCount is incremented when new objects are created from class factories, and is decremented when objects are destroyed.

When ObjectCount is zero the server can be unloaded. At this time, code written for the OnLastRelease event handler can process special actions after the last object is released and before the server shuts down.


TComServer::ServerFileName

TComServer	See also

Specifies the complete path and file name of the COM server.

Description

ServerFileName contains a the module name of the COM server. This name includes the path and extension of the file name for the module.


TComServer::ServerKey

TComServer

Indicates whether the COM server is an in-process server or whether it is a local server.

Description

ServerKey contains the string 'InprocServer32' if the server is a DLL and 'LocalServer32' if the server is an EXE.


TComServer::ServerName

TComServer	See also

Specifies the name of the file for the server.

Description

ServerName contains the file name, excluding the path and extension, of the COM server.


TComServer::StartMode

TComServer	See also

Indicates why the COM server was started.

Description

StartMode indicates the reason a COM server was started: as a stand-alone, as an interactive application, as an embedded object, or for registration or unregistration.

TStartMode is the type of the StartMode property, indicating the different reasons why an OLE automation server can be started.

The following table explains each of the possible start-mode values and the command-line switch that corresponds to each.

Start mode	Switch	Meaning

smAutomation	embedding	The application was started by Windows in response to a request from an automation controller.

smRegServer	regserver	The application was started only to add the server to the system registry.

smStandalone	---	The user started the application as a stand-alone, interactive application.

smUnregServer	unregserver	The application was started only to remove the server from the system registry.


TComServer::TypeLib

TComServer

Provides access to the type library associated with the COM server.

Description

Use TypeLib to access the type library for the COM server. TypeLib is a reference to an ITypeLib interface.


TComServer events

TComServer	Alphabetically

In TComServer

OnLastRelease


TComServer events

TComServer	By object

OnLastRelease


TComServer::OnLastRelease

TComServer	See also

Occurs when the last object using the server is released.

Description

Use OnLastRelease to write a handler to process some action after the last object using the server is released, and just before the server shuts down. ShutDown indicates whether the server should be unloaded.

TLastReleaseEvent is the type of the OnLastRelease event. Shutdown indicates whether the server will shut down after processing the OnLastRelease event.


TComServer methods

TComServer	Alphabetically

In TComServer

~TComServer

Initialize

LoadTypeLib

SetServerName

TComServer

UpdateRegistry

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComServer methods

TComServer	By object

~TComServer

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

Initialize

InitInstance

InstanceSize

LoadTypeLib

MethodAddress

MethodName

NewInstance

SafeCallException

SetServerName

TComServer

UpdateRegistry


TComServer::TComServer

TComServer	See also

Creates a COM server object.

Description

Applications do not need to call the constructor for TComServer.  An instance of TComServer is automatically created as the ComServ variable in modules that are servers for COM objects.

TComServer allocates memory for a COM server object, and initializes its IsInprocServer and StartMode properties. It is not necessary to directly call the constructor to create a COM server object. A global ComServer variable is declared in the ComServ unit and is instantiated in the initialization section.


TComServer::~TComServer

TComServer	See also

Destroys an instance of a COM server object.

Description

It is not necessary to directly call Free (or ~TComServer) to destroy a COM server object. The global ComServ variable, declared in the ComServ unit, is automatically created and destroyed in the initialization and finalization sections.

~TComServer destroys the COM server object and calls the ComClassManger to free, from the list it maintains, each of the class factories that the server owns.

Note:	For applications that handle destruction of an object, the application should always call Free instead. Free verifies that the COM server object has not already been freed before it calls ~TComServer.


TComServer::Initialize

TComServer	See also

Updates the registry and registers the class objects.

Description

Initialize updates the registry if the server was not started only to remove the server from the system registry. Then, if the server was started as an interactive stand-alone application, or in response to a request from an automation controller, Initialize calls on each class factory, owned by the server, to register its class object in the system registry.


TComServer::LoadTypeLib

TComServer	See also

Loads the type library for the server.

Description

LoadTypeLib loads the type library for the server. If the type library is not already loaded when LoadTypeLib is called, it also registers the type library.

If LoadTypeLib is not successful, it raises an EOleSysError indicating the error code. The possible error codes are as follows:

Error code	Meaning

E_OUTOFMEMORY	Out of memory.

E_INVALIDARG	One or more of the arguments is invalid.

TYPE_E_IOERROR	The function could not write to the file.

TYPE_E_INVALIDSTATE	The type library could not be opened.

TYPE_E_INVDATAREAD	The function could not read from the file.

TYPE_E_UNSUPFORMAT	The type library has an older format.

TYPE_E_UNKNOWNLCID	The LCID could not be found in the OLE support DLLs.

TYPE_E_CANTLOADLIBRARY	The type library or DLL could not be loaded.

Other return codes	All FACILITY_STORAGE errors may be returned.


TComServer::SetServerName

TComServer	See also

Sets the ServerName property.

Description

Call SetServerName to provide a name for the server. If the server has an associated type library (the TypeLib property is NULL), SetServerName does nothing, because the name for the server must match the name specified in the type library.


TComServer::UpdateRegistry

TComServer	See also

Registers information on classes implemented in the COM server.

Description

UpdateRegistry updates the registry to reflect the current status of the COM server. Accordingly UpdateRegistry either registers or unregisters the type library information and the CLSIDs associated with the class factories instantiated by the COM server.

The global functions that register and unregister the server call UpdateRegistry. UpdateRegistry is also called by the Initialize method.


Accessibility

Read-only


Hierarchy

TObject

TComServerObject


TComServerObject

Hierarchy	Properties	Methods	See also

TComServerObject is the abstract base class for TComServer.

Unit

comobj

Description

TComServerObject is used as a base class for the TComServer class. All of its methods are abstract and protected. The TComServerObject introduces protected abstract methods that are overridden in descendant classes as accessor functions for its properties. These methods are implemented in the TComServer class. All of the properties of TComServerObject are read-only.

To use a COM server object, include the ComServ unit in the project. This unit automatically instantiates the descendant TComServer class and assigns that object to the ComServ variable in the ComServ unit.


TComServerObject properties

TComServerObject	Alphabetically	Legend

In TComServerObject

HelpFileName

ServerFileName

ServerKey

ServerName

TypeLib


TComServerObject properties

TComServerObject	By object	Legend

HelpFileName

ServerFileName

ServerKey

ServerName

TypeLib


TComServerObject::HelpFileName

TComServerObject

Specifies the name of the Help file associated with the module.

__property System::AnsiString HelpFileName = {read=GetHelpFileName};

Description

The abstract accessor methods for HelpFileName are overridden in descendant classes.


TComServerObject::ServerFileName

TComServerObject	See also

Specifies the complete path and filename of the COM server.

__property System::AnsiString ServerFileName = {read=GetServerFileName};

Description

The abstract accessor methods for ServerFileName are overridden in descendant classes.


TComServerObject::ServerKey

TComServerObject

Indicates whether the COM server is an in-process server or whether it is a local server.

__property System::AnsiString ServerKey = {read=GetServerKey};

Description

The abstract accessor methods for ServerKey are overridden in descendant classes.


TComServerObject::ServerName

TComServerObject	See also

Specifies the name of the executable file for the server.

__property System::AnsiString ServerName = {read=GetServerName};

Description

The abstract accessor methods for ServerName are overridden in descendant classes.


TComServerObject::TypeLib

TComServerObject

Provides access to the type library associated with the COM server.

__property _di_ITypeLib TypeLib = {read=GetTypeLib};

Description

The abstract accessor methods for TypeLib are overridden in descendant classes.


TComServerObject methods

TComServerObject	Alphabetically

In TComServerObject

~TComServerObject

TComServerObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TComServerObject methods

TComServerObject	By object

~TComServerObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TComServerObject


TComServerObject::TComServerObject

TComServerObject

TComServerObject creates a new TComServerObject object.

__fastcall TComServerObject(void) : System::TObject() { }


TComServerObject::~TComServerObject

TComServerObject

~TComServerObject frees the memory associated with the TComServerObject object. Do not call ~TComServerObject directly. Instead, use the delete keyword on the object, which causes ~TComServerObject to be invoked automatically.

__fastcall virtual ~TComServerObject(void) { }


Accessibility

Read-only


Hierarchy

TObject


TConnectionPoints

Hierarchy	Properties	Methods

TConnectionPoints implements a container for connection points.

Unit

axctrls

Description

TConnectionPoints lets an object to indicate the existence of outgoing interfaces.

The IConnectionPointContainer interface is implemented on a connectable object to indicate the existence of the outgoing interfaces. It provides access to an enumerator sub-object with the IEnumConnectionPoints interface.

It also provides access to all the connection point sub-objects, each of which implements the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

TConnectionPoints objects are used to obtain access to:

•	An enumerator sub-object with the IEnumConnectionPoints interface. The IEnumConnectionPoints interface can be used to enumerate connection points for each outgoing IID.

•	Connection point sub-objects with the IConnectionPoint interface for each outgoing IID. Through the IConnectionPoint interface, a client starts or terminates an advisory loop with the connectable object and the client's own sink. The client can also use the IConnectionPoint interface to obtain an enumerator object with the IEnumConnections interface to enumerate the connections that it knows about.

The IConnectionPoint and IConnectionPointContainer interfaces are used for OLE event handling.

Interface implemented

IConnectionPointContainer


TConnectionPoints properties

TConnectionPoints	Alphabetically	Legend

Derived from TAggregatedObject

Controller


TConnectionPoints properties

TConnectionPoints	By object	Legend

Controller


TConnectionPoints methods

TConnectionPoints	Alphabetically

In TConnectionPoints

~TConnectionPoints

CreateConnectionPoint

TConnectionPoints

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TConnectionPoints methods

TConnectionPoints	By object

~TConnectionPoints

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateConnectionPoint

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TConnectionPoints


TConnectionPoints::TConnectionPoints

TConnectionPoints	See also

Instantiates a connection points object.

__fastcall TConnectionPoints(const _di_IUnknown Controller);

Description

TConnectionPoints is automatically called to instantiate a connection points object. It is not necessary to call TConnectionPoints directly. It is used internally by other objects to create the connection points object.

TConnectionPoints allocates memory for a connection points object, and calls the parent object's constructor passing it the Controller, as the controlling unknown in the aggregate. Then it creates a list for the individual connection point objects that it will contain.


TConnectionPoints::TConnectionPoints
TConnectionPoints::CreateConnectionPoint

TConnectionPoints	See also

Instantiates a connection point object.

TConnectionPoint* __fastcall CreateConnectionPoint(const GUID &IID, TConnectionKind Kind, TConnectEvent&OnConnect);

Description

CreateConnectionPoint is automatically called when an ActiveX control is initialized. CreateConnectionPoint creates and returns a connection point object. It passes to the connection point constructor:

•	Itself as the connection point container.

•	IID as the GUID or interface identifier of the outgoing interface managed by this connection point.

•	OnConnect as the connection event used in the IConnectionPoint Advise method.

TConnectEvent is a pointer to a procedure for the OnConnect event of the connection point object being created.  TConnectionKind is a type indicating whether there are multiple connections to that connection point.


TConnectionPoints::~TConnectionPoints

TConnectionPoints

Destroys an instance of a connection points object.

__fastcall virtual ~TConnectionPoints(void);

Description

~TConnectionPoints is called automatically. It is not necessary for the user to dispose of the connection points object. ~TConnectionPoints frees the list of connection point objects that was created in the constructor.

Note:	Applications that do need to handle the desctruction of the object should not call ~TConnectionPoints directly, but rather, they should use the delete keyword.


Accessibility

Read-only


Hierarchy

TObject

TAggregatedObject


TConnectionPoint

Hierarchy	Properties	Methods	See also

TConnectionPoint is the class used to create connection point objects for connection point containers.

Unit

axctrls

Description

TConnectionPoint is a class that implements the IConnectionPoint interface. It is used to create objects that are connection points for connectable objects. Connectable objects support the following features:

•	Outgoing interfaces, such as event sets.

•	The ability to enumerate the IIDs of the outgoing interfaces.

•	The ability to connect and disconnect sinks to the object for those outgoing IIDs.

•	The ability to enumerate the connections that exist to a particular outgoing interface.

The IConnectionPoint and IConnectionPointContainer interfaces are used for OLE event handling.

Implemented methods of IConnectionPoint

GetConnectionInterface, GetConnectionPointContainer, Advise, Unadvise, EnumConnections


TConnectionPoint properties

TConnectionPoint	Alphabetically	Legend

Derived from TAggregatedObject

Controller


TConnectionPoint properties

TConnectionPoint	By object	Legend

Controller


TConnectionPoint methods

TConnectionPoint	Alphabetically

In TConnectionPoint

~TConnectionPoint

TConnectionPoint

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TConnectionPoint methods

TConnectionPoint	By object

~TConnectionPoint

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TConnectionPoint


TConnectionPoint::TConnectionPoint

TConnectionPoint	See also

Instantiates a connection point object.

__fastcall TConnectionPoint(TConnectionPoints* Container, const GUID &IID, TConnectionKind Kind, TConnectEvent&OnConnect);

Description

TConnectionPoint is called automatically, by the connection point container’s CreateConnectionPoint method, to instantiate a connection point object. This occurs when an ActiveX control is initialized.

TConnectionPoint allocates memory for a connection point object, and calls the parent object's constructor, passing it the Container’s controlling IUnknown. Container is a connection point container object. TConnectionPoint adds the connection point object to the Container. Then it sets the

•	IID as the GUID or interface identifier of the outgoing interface managed by this connection point.

•	IKind, indicating whether it is a single or multiple connection to that point.

•	OnConnect as the connection event used in the IConnectionPoint Advise method to .

TConnectEvent points to a procedure for the OnConnect event of the connection point. TConnectionKind is a type indicating whether there are multiple connections to the connection point.


TConnectionPoint::~TConnectionPoint

TConnectionPoint	See also

Destroys the instance of a connection point object.

__fastcall virtual ~TConnectionPoint(void);

Description

It is not necessary to dispose of the connection point object. Connection point objects are automatically destroyed. If the connection point container object is not NULL, ~TConnectionPoint calls on it to remove the connection point object from it.

Note:	For applications that need to handle the destruction of an object should not call ~TConnectionPoint directly. Instead, those applications should use the delete keyword.


Accessibility

Read-only


Hierarchy

TObject

TAggregatedObject

TContainedObject


TControl

Hierarchy	Properties	Methods	Events	See also

TControl is the abstract base class for all visual components.

Unit

controls

Description

Controls are visual components, meaning the user can see them and manipulate them at runtime. All controls have properties, methods, and events in common that are specific to the visual aspect of controls, such as the position of the control, the cursor or hint associated with the control’s window, methods to paint or move the control, and events to respond to mouse actions.

TControl has many protected properties and methods that are used or published by its descendants.


TControl properties

TControl	Alphabetically	Legend

In TControl

Align

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ControlState

ControlStyle

Cursor

DesktopFont

DragCursor

DragMode

Enabled

Font

Height

Hint

IsControl

Left

MouseCapture

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ScalingFlags

ShowHint

Text

Top

Visible

Width

WindowProc

WindowText

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TControl properties

TControl	By object	Legend

Align

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

DesktopFont

DragCursor

DragMode

Enabled

Font

Height

Hint

IsControl

Left

MouseCapture

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ScalingFlags

ShowHint

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc

WindowText


TControl::Align

TControl	See also 	Example

Determines how the control aligns within its container (or parent control).

enum TAlign { alNone, alTop, alBottom, alLeft, alRight, alClient };

__property TAlign Align = {read=FAlign, write=SetAlign, default=0};

Description

Use Align to align a control to the top, bottom, left, or right of a form or panel and have it remain there even if the size of the form, panel, or component that contains the control changes.

For example, to use a panel component with various controls on it as a tool palette, change the panel’s Align value to alLeft. The value of alLeft for the Align property of the panel guarantees that the tool palette remains on the left side of the form and always equals the client height of the form.

The default value of Align is alNone, which means a control remains where it is positioned on a form or panel. Specify another value to align the control. Use one of these possible values:

Value	Meaning

alNone	The component remains where it was placed on the form or panel. This is the default value.

alTop	The component moves to the top of the form and resizes to fill the width of the form. The height of the component is not affected.

alBottom	The component moves to the bottom of the form and resizes to fill the width of the form. The height of the component is not affected.

alLeft	The component moves to the left side of the form and resizes to fill the height of the form. The width of the component is not affected.

alRight	The component moves to the right side of the form and resizes to fill the height of the form. The width of the component is not affected.

alClient	The component resizes to fill the client area of a form. If a component already occupies part of the client area, the component resizes to fit within the remaining client area.

Note:	If Align is set to alClient, the control fills the entire client area so that it is impossible to select the parent form by clicking on it. In this case, select the parent by selecting the control on the form and pressing Esc, or by using the Object Inspector.

Any number of child components within a single parent can have the same Align value, in which case they stack up along the edge of the parent form or panel. The child controls stack up in z-order. To adjust the order in which the controls stack up, drag the controls into their desired positions.


TControl::BoundsRect

TControl	See also 	Example

Specifies the bounding rectangle of the control, expressed in the coordinate system of the parent control.

__property Windows::TRect BoundsRect = {read=GetBoundsRect, write=SetBoundsRect};

Description

Use BoundsRect as a quick way to obtain the pixel locations of all corners of the control all at once.

For example, the statement

R = Control->BoundsRect;

corresponds to

R.Left = Control->Left;

R.Top = Control->Top;

R.Right = Control->Left + Control->Width;

R.Bottom = Control->Top + Control->Height;

The TRect type defines a rectangle. The coordinates are specified both as four separate integers representing the pixel locations of the left, top, right, and bottom sides, and as two points representing the pixel locations of the top left and bottom right corners. The origin of the pixel coordinate system is in the top left corner of the parent window.


TControl::Caption

TControl	See also	Example

Specifies a text string that identifies the control to the user.

__property System::AnsiString Caption = {read=GetText, write=SetText};

Description

Use Caption to associate the control with a text string that identifies the control. For most controls, the Caption is the window title and it appears as a label for the control.

To underline a character in a Caption that labels a component, include an ampersand (&) before the character. This type of character is called an accelerator character. The user can then select the component by pressing Alt while typing the underlined character. To display an ampersand character in the caption, use two ampersands (&&).


TControl::ClientHeight

TControl	See also

Specifies the height of the control's client area in pixels.

__property int ClientHeight = {read=GetClientHeight, write=SetClientHeight, stored=false, nodefault};

Description

Use ClientHeight to read or change the height of the control’s client area.

For TControl, ClientHeight is the same as Height. Derived classes may implement a ClientHeight property that differs from Height. For example, the ClientHeight of a form is the value of the Height property minus the height of the title bar, resize border, and scrollbars.


TControl::ClientOrigin

TControl	See also	Example

Specifies the screen coordinates (in pixels) of the top left corner of a control’s client area.

__property tagPOINT ClientOrigin = {read=GetClientOrigin};

Description

Read ClientOrigin to locate the top-left corner of the control’s client area. ClientOrigin returns X and Y coordinates in a record of type TPoint, with the origin in the top left corner. X specifies the horizontal coordinate of the point, Y specifies the vertical coordinate.

The screen coordinates of a control that is descended from TControl and not TWinControl are actually the screen coordinates of the control’s parent added to its Left and Top properties. If the control doesn’t have a parent, an EInvalidOperation exception is thrown when ClientOrigin is read.


TControl::ClientRect

TControl	See also 	Example

Specifies the size (in pixels) of a control client area.

__property Windows::TRect ClientRect = {read=GetClientRect};

Description

Read ClientRect to find the size of the client area of a control. ClientRect returns a rectangle with its Top and Left fields set to zero, and its Bottom and Right fields set to the control's Height and Width, respectively. ClientRect is equivalent to Rect(0, 0, ClientWidth, ClientHeight).

The TRect type defines a rectangle. The coordinates are specified both as four separate integers representing the pixel locations of the left, top, right, and bottom sides, and as two points representing the pixel locations of the top left and bottom right corners.


TControl::ClientWidth

TControl	See also	Example

Specifies the horizontal size of the control's client area in pixels.

__property int ClientWidth = {read=GetClientWidth, write=SetClientWidth, stored=false, nodefault};

Description

Use ClientWidth to read or change the width of the control’s client area. ClientWidth is equivalent to ClientRect::Right.

For TControl, ClientWidth is the same as Width. Derived classes may implement a ClientWidth property that differs from Width. For example, the ClientWidth of a form is the value of the Width property minus the width of the resize border and scrollbars.


TControl::Color

TControl	See also 	Example

Specifies the background color of the control.

__property Graphics::TColor Color = {read=FColor, write=SetColor, stored=IsColorStored, default=-2147483643 };

Description

Use Color to read or change the background color of the control.

If a control's ParentColor property is true, then changing the Color property of the control's parent automatically changes the Color property of the control. When the value of the Color property is changed, the control's ParentColor property is automatically set to false.


TControl::ControlState

TControl	See also

Indicates the current state of a control at runtime.

enum Controls__4 { csLButtonDown, csClicked, csPalette, csReadingState, csAlignmentNeeded, csFocusing, csCreating, csPaintCopy };

typedef Set<Controls__4, csLButtonDown, csPaintCopy> TControlState;

__property TControlState ControlState = {read=FControlState, write=FControlState, nodefault};

Description

Read ControlState to find out various conditions that affect the control such as whether it has been clicked or needs alignment. ControlState reflects transient conditions of an instance of the control, as opposed to attributes of the control class as a whole. ControlState consists of a set of flags drawn from the following values:

Flag	Meaning

csLButtonDown	The left mouse button was clicked and not yet released. This is set for all mouse-down events.

csClicked	The same as csLButtonDown, but only set if ControlStyle contains csClickEvents, meaning that mouse-down events are interpreted as clicks.

csPalette	A WM_PALETTCHANGED message was received by the control or one of its parents.

csReadingState	The control is reading its state from a stream.

csAlignmentNeeded	The control needs to realign itself when alignment is re-enabled.

csFocusing	The application is processing messages intended to give the control focus. This does not guarantee the control will receive focus, but prevents recursive calls.

csCreating	The control and/or its owner and subcontrols is being created. This flag clears when all have finished creating.

csPaintCopy	The control is being replicated, meaning a copy of the control is being painted. The ControlStyle flag csReplicatable must be set for this state to occur.

The flags in ControlState are specific to controls, and are in addition to the state flags in the ComponentState property, which apply to all components.

ControlState is primarily used by component writers in the implementation of components derived from TControl.


TControl::ControlStyle

TControl	See also

Determines style characteristics of the control.

enum Controls__5 { csAcceptsControls, csCaptureMouse, csDesignInteractive, csClickEvents, csFramed,	csSetCaption, csOpaque, csDoubleClicks, csFixedWidth, csFixedHeight, csNoDesignVisible, csReplicatable, csNoStdEvents, csDisplayDragImage, csReflector };

typedef Set<Controls__5, csAcceptsControls, csReflector> TControlStyle;

__property TControlStyle ControlStyle = {read=FControlStyle, write=FControlStyle, nodefault};

Description

Use ControlStyle to determine various attributes of the control, such as whether the control can capture the mouse or has a fixed size. The ControlStyle property contains a set of style flags indicating these attributes. The following table lists the flags and their meanings:

Flag	Meaning

csAcceptsControls	The control becomes the parent of any controls dropped on it at design time.

csCaptureMouse	The control captures mouse events when it is clicked.

csDesignInteractive	The control maps right mouse-button clicks at design time into left-button clicks to manipulate the control.

csClickEvents	The control can receive and respond to mouse clicks.

csFramed	The control has a 3D frame.

csSetCaption	The control should change its caption to match the Name property if the caption has not been explicitly set to something else.

csOpaque	The control completely fills its client rectangle.

csDoubleClicks	The control can receive and respond to double-click messages. Otherwise, map double-clicks into clicks.

csFixedWidth	The width of the control does not vary or scale.

csFixedHeight	The height of the control does not vary or scale.

csNoDesignVisible	The control is not visible at design time.

csReplicatable	The control can be copied using the PaintTo method to draw its image to an arbitrary canvas.

csNoStdEvents	Standard events such as mouse, key, and click events are ignored. Use this setting if your code doesn’t need to respond to these events and your application will run faster.

csDisplayDragImage	The control can display an image from an image list when the mouse is dragged over the control. Use this setting if the control implements an image list for when the mouse is dragged over it.

csReflector	The control responds to Windows dialog messages, focus messages, or size change messages. Use this setting if the control can be used as an ActiveX control, so that it will receive notification of these events.

ControlStyle generally describes an entire class, which all instances reflect. The flags do not change among different instances of a type of control, nor do they vary at runtime. Such transient conditions are indicated by the ControlState property.

The Create method of TControl initializes ControlStyle to include csCaptureMouse, csClickEvents, csSetCaption, and csDoubleClicks.

ControlStyle is primarily used by component writers in the implementation of components derived from TControl.


TControl::Cursor

TControl	See also 	Example

Specifies the image used to represent the mouse pointer when it passes into the region covered by the control.

__property TCursor Cursor = {read=FCursor, write=SetCursor, default=0};

Description

Change the value of Cursor to provide feedback to the user about what action is appropriate when the mouse pointer enters the control.

The value of Cursor is the index of the cursor in the list of cursors maintained by the global variable, Screen. In addition to the built-in cursors provided by TScreen, applications can add custom cursors to the list. These are the built-in values provided by TScreen:

Value	Image

crDefault	Whatever cursor is the default for the window class. Usually crArrow.

crNone

crArrow

crCross

crIBeam

crSize

crSizeNESW

crSizeNS

crSizeNWSE

crSizeWE

crUpArrow

crHourGlass

crDrag

crNoDrop

crHSplit

crVSplit

crMultiDrag

crSQLWait

crNo

crAppStart

crHelp

crHandPoint

Note:	The example shows how to make a custom cursor available to an application.


TControl::DesktopFont

TControl	See also

Specifies whether the control uses the Windows icon font when writing text.

__property bool DesktopFont = {read=FDesktopFont, write=SetDesktopFont, default=0};

Description

Set DesktopFont to true to specify that the control should use the Windows icon font for its Font property. The Windows icon font is the value of the IconFont property of the global Screen variable.

When DesktopFont is true, the Font property of the control updates every time the Windows icon font is changed. This font can be changed by setting the IconFont property of the global Screen variable, or by the actions of other programs. Setting the Font property to Screen::IconFont will not allow controls to respond to changes in the Windows icon font in this manner.


TControl::DragCursor

TControl	See also	Example

Indicates the image used to represent the mouse pointer when the control is being dragged.

__property TCursor DragCursor = {read=FDragCursor, write=FDragCursor, default=-12};

Description

Use the DragCursor property to change the cursor image presented when the control is being dragged. The possible values for the DragCursor property are the same as those for the Cursor property. See the table in the Cursor property entry.

Note:	To learn how to make a custom cursor available for the DragCursor property, see the Cursor property.


TControl::DragMode

TControl	See also	Example

Determines the drag and drop behavior of a control.

enum TDragMode { dmManual, dmAutomatic };

__property TDragMode DragMode = {read=FDragMode, write=SetDragMode, default=0};

Description

Use the DragMode property to control when the user is able to drag the control. Disable the drag and drop capability at runtime by changing the DragMode property value to dmManual.

These are the possible values:

Value	Meaning

dmAutomatic	If dmAutomatic is selected, the control is ready to be dragged; the user just clicks and drags it.

dmManual	If dmManual is selected, the control can't be dragged until the application calls the BeginDrag method.


TControl::Enabled

TControl	See also	Example

Controls whether the control responds to mouse, keyboard, and timer events.

__property bool Enabled = {read=FEnabled, write=SetEnabled, default=1};

Description

Use Enabled to change the availability of the control to the user. To disable a control, set Enabled to false. Disabled controls appear dimmed. If Enabled is false, the control ignores mouse and keyboard events.

To re-enable a control, set Enabled to true. The control is no longer dimmed, and the user can use the control.


TControl::Font

TControl	See also	Example

Controls the attributes of text written on or in the control.

__property Graphics::TFont* Font = {read=FFont, write=SetFont, stored=IsFontStored};

Description

To change to a new font, specify a new TFont object. To modify a font, change the value of the Color, Height, Name, Pitch, Size, or Style of the TFont object.


TControl::Height

TControl	See also	Example

Specifies the vertical size of the control in pixels.

__property int Height = {read=FHeight, write=SetHeight, nodefault};

Description

Use the Height property to read or change the height of the control.


TControl::Hint

TControl	See also 	Example

Contains the text string that can appear when the user moves the mouse over the control.

__property System::AnsiString Hint = {read=FHint, write=FHint};

Description

Use the Hint property to provide a string of help text either as a Help Hint, or as help text on a particular location such as a status bar.

A Help Hint is a box containing help text that appears for a control when the user moves the mouse pointer over the control and pauses momentarily. To set up Help Hints:

1	Specify the Hint property for each control that a Help Hint should appear for.

2	Set the ShowHint property of each appropriate control to true, or set the ParentShowHint property of all controls to true and set the ShowHint property of the form to true.

3	At runtime, set the value of the application's ShowHint property to true.

To show the Hint on a status bar or other location, use the OnHint event handler of the application. The application’s OnHint event occurs when the mouse pointer moves over the control. Write an OnHint event handler to display the hint as the caption of a panel component that is used as a status bar.

Specify a hint to be used for both a Help Hint box and by an OnHint handler by specifying two values separated by a | character (the vertical bar “or” symbol). For example,

Edit1->Hint = "Name|Enter Name in the edit box";

The "Name" string appears in the Help Hint box, and the "Enter full name in the edit box" string appears as specified in the OnHint event handler.

If you specify just one value, it can be used as both a Help Hint and as the Hint property of the application. If the application's ShowHint property is false, the Help Hint won't appear, but the OnHint event handler will still be called.

If a control has no Hint value specified, but its parent control does, the control uses the Hint value of the parent control as long as the control's ShowHint property is true.


TControl::IsControl

TControl	See also

Determines whether a form stores its form-specific properties to a stream.

__property bool IsControl = {read=FIsControl, write=FIsControl, nodefault};

Description

Use IsControl to use a form as a complex control, rather than as a desktop form. IsControl affects the way the form gets saved. When IsControl is true, form-specific properties do not get saved with the form. When IsControl is false, the form-specific properties get saved along with the other properties.

IsControl permits you to use the forms designer to create complex controls such as panels, by creating those controls as forms, placing and naming their contained controls, and attaching code to events. After saving the form, edit the form as text, and in the text version set IsControl to true. The next time the form is reloaded and saved, only those form properties appropriate to use as a control are stored, not the properties specific to TForm. Next, edit the form file as text, changing the type of the component from TForm to the desired control type, such as TPanel.


TControl::Left

TControl	See also 	Example

Specifies the horizontal coordinate of the left edge of a component relative to the form in pixels.

__property int Left = {read=FLeft, write=SetLeft, nodefault};

Description

Use the Left property to determine where the left side of the control begins or to reposition the left side of the control.

If the control is contained in another control, such as a TPanel, the Left and Top properties are relative to the parent control. If the control is contained directly by the form, the properties values are relative to the form. For forms, the value of the Left property is relative to the screen in pixels.


TControl::MouseCapture

TControl	See also

Indicates whether the control has “captured” mouse events.

__property bool MouseCapture = {read=GetMouseCapture, write=SetMouseCapture, nodefault};

Description

Use MouseCapture to determine whether a control has captured the mouse. The capture control is the control to which all subsequent mouse events go until the user releases the mouse button.

A control becomes the capture control when the user drags an item from it. In addition, if the control has the csCaptureMouse flag set in its ControlStyle property, it becomes the capture control when the user presses the left mouse button over it, until the user releases the mouse button.


TControl::Name

TControl	See also

Specifies the name of the control as referenced in the application’s code.

__property System::AnsiString Name = {read=FName, write=SetName, stored=false};

Description

Use the Name property to assign a new name to the control or to find out what the name of the control is.

By default, the IDE assigns sequential names based on the type of the control, such as 'Button1', 'Button2', and so on. Change these to more meaningful names that make the application’s code more readable. The Name must be a valid Object Pascal identifier. If the control’s Caption has not already been modified, the Caption is changed to match the new control name.

Warning:	Change control names only at design time.


TControl::Parent

TControl	See also 	Example

Inidicates the parent of the control and determines where the control is displayed.

__property TWinControl* Parent = {read=FParent, write=SetParent};

Description

Use the Parent property to determine the parent of this control or to assign a control to be the parent of this control. When creating a new control, always assign a Parent property value for the new control. Usually, this is a form, panel, group box, or some control that is designed to contain another. Changing the parent of a control moves the control onscreen so that it is displayed within the parent.

The parent of a control is the windowed control that contains the control. If one control (parent) contains others, the contained controls are child controls of the parent. For example, if an application includes three radio buttons in a group box, the group box is the parent of the three radio buttons, and the radio buttons are the child controls of the group box.

Don't confuse the Parent property declared in TControl with the Owner property declared in TComponent. The Parent of a control is always a windowed control that visually contains the control. The Owner of a component is the component that was passed as a parameter in the constructor and that controls when the component is freed.


TControl::ParentColor

TControl	See also	Example

Determines where a control looks for its color information.

__property bool ParentColor = {read=FParentColor, write=SetParentColor, default=1};

Description

To have a control use the same color as its parent control, set ParentColor to true. For example, if the ParentColor of a list box on a panel is true, the list box has the same color as the panel. If ParentColor is false, the control uses its own Color property.

Set ParentColor to true for all controls in order to ensure that all the controls on a form have a uniform appearance. For example, if ParentColor is true for all controls in a form, changing the background color of the form to gray causes all the controls on the form to also have a gray background.

To specify a different color for a particular control, assign the desired color to that control's Color property, and ParentColor becomes false automatically.


TControl::ParentFont

TControl	See also	Example

Determines where a control looks for its font information.

__property bool ParentFont = {read=FParentFont, write=SetParentFont, default=1};

Description

To have a control use the same font as its parent control, set ParentFont to true. For example, if the ParentFont of a list box on a panel is true, the list box uses the same font as the panel. If ParentFont is false, the control uses its own Font property.

Set ParentFont to true for all controls in order to ensure that all the controls on a form have a uniform appearance. For example, if ParentFont is true for all controls in a form, changing the form’s Font property to 12-point Courier causes all controls on the form to use that font.

To specify a different font for a particular control, change the control's Font property, and ParentFont becomes false automatically.

When the ParentFont is true for a form, the form uses the value of the application's Font property.


TControl::ParentShowHint

TControl	See also	Example

Determines where a control looks to find out if the Help Hint, specified as the value of the Hint property for the control, should be shown.

__property bool ParentShowHint = {read=FParentShowHint, write=SetParentShowHint, default=1};

Description

Use ParentShowHint to ensure that all the controls on a form either uniformly show their Help Hints or uniformly don't show them.

If ParentShowHint is true, the control uses the ShowHint property value of its parent. If ParentShowHint is false, the control uses the value of its own ShowHint property.

To provide Help Hints for only selected controls on a form, set the ShowHint property for those controls that should have Help Hints to true, and ParentShowHint becomes false automatically.

Note:	Enable or disable all Help Hints for the entire application using the ShowHint property of the application object.


TControl::PopupMenu

TControl	See also 	Example

Identifies the pop-up menu associated with the control.

__property Menus::TPopupMenu* PopupMenu = {read=FPopupMenu, write=SetPopupMenu};

Description

Assign a value to PopupMenu to make a pop-up menu appear when the user selects the control and clicks the right mouse button. If the TPopupMenu’s AutoPopup property is true, the pop-up menu appears automatically. If the menu’s AutoPopup property is false, display the menu with a call to its Popup method.


TControl::ScalingFlags

TControl	See also

Reflects which attributes of the control have not yet been scaled.

enum Controls__6 { sfLeft, sfTop, sfWidth, sfHeight, sfFont };

typedef Set<Controls__6, sfLeft, sfFont>  TScalingFlags;

__property TScalingFlags ScalingFlags = {read=FScalingFlags, write=FScalingFlags, nodefault};

Description

ScalingFlags is an internal set of flags used primarily in scaling inherited forms and their controls. Applications should not use this property without a serious need.

These are the flags and their meanings:

Flag	Meaning

sfLeft	Left side of control not yet scaled.

sfTop	Top of control not yet scaled.

sfWidth	Width of control not yet scaled.

sfHeight	Height of control not yet scaled.

sfFont	Font of control not yet scaled.


TControl::ShowHint

TControl	See also 	Example

Determines if the control should display a Help Hint when the mouse pointer rests momentarily on the control.

__property bool ShowHint = {read=FShowHint, write=SetShowHint, stored=IsShowHintStored, nodefault};

Description

The Help Hint is the value of the Hint property, which is displayed in a box just beneath the control. Use ShowHint to determine whether a Help Hint appears for the control.

To enable Help Hint for a particular control, the application ShowHint must be true and either

•	the control’s own ShowHint property must be true, or

•	the control’s ParentShowHint property must be true and its parent's ShowHint property must be true.

For example, imagine a check box within a group box. If the ShowHint property of the group box is true and the ParentShowHint property of the check box is true, but the ShowHint property of the check box is false, the check box will still display its Help Hint.

Changing the ShowHint value automatically sets the ParentShowHint property to false.


TControl::Text

TControl	See also 	Example

Contains a text string associated with the control.

__property System::AnsiString Text = {read=GetText, write=SetText};

Description

Use the Text property to read the Text of the control or specify a new string for the Text value. By default, Text is the control name. For edit controls and memos, the Text appears within the control. For combo boxes, the Text is the content of the edit control portion of the combo box.


TControl.Top
TControl::Top

TControl	See also	Example

Specifies the Y coordinate of the top left corner of a control, relative to its parent or containing control in pixels.

__property int Top = {read=FTop, write=SetTop, nodefault};

Description

Use the Left property to locate the top of the control or reposition the control to a different Y coordinate. The Top property, like the Left property, is the position of the control relative to its container. Thus, if a control is contained in a TPanel, the Left and Top properties are relative to the panel. If the control is contained directly by the form, it is relative to the form. For forms, the value of the Left property is relative to the screen in pixels.


TControl::Visible

TControl	See also	Example

Determines whether the component appears onscreen.

__property bool Visible = {read=FVisible, write=SetVisible, default=1};

Description

Use the Visible property to control the visibility of the control at runtime. If Visible is true, the control appears. If Visible is false, the control is not visible.

Calling the Show method sets the control's Visible property to true. Calling the Hide method sets it to false.


TControl::Width

TControl	See also	Example

Specifies the horizontal size of the control or form in pixels.

__property int Width = {read=FWidth, write=SetWidth, nodefault};

Description

Use the Width property to read or change the width of the control.

Note:	For tab sheet controls, changing this property at runtime has no effect.


TControl::WindowProc

TControl	See also

Points to the window procedure that responds to messages sent to the control.

typedef void __fastcall (__closure *TWndMethod)(Messages::TMessage &Message);

__property TWndMethod WindowProc = {read=FWindowProc, write=FWindowProc};

Description

Use the WindowProc property to temporarily replace or subclass the window procedure of the control. Component writers that are customizing the window procedure for a descendent class should override the WndProc method instead.

Before assigning a new value to WindowProc, store the original value. WindowProc is initially set to the WndProc method, so if the value has not been changed since then, the original value need not be stored. Within the procedure that is used as the new value for WindowProc, pass any unhandled messages to the original procedure that was the value of WindowProc. After completing any specialized message handling, restore the value of WindowProc to the original procedure.


TControl::WindowText

TControl	See also

Contains the text string of the control.

__property char* WindowText = {read=FText, write=FText};

Description

Use WindowText to determine the text associated with the control. When setting WindowText, the control frees the memory associated with the previous value of WindowText before assigning a new value. Any memory associated with WindowText is freed when the control is destroyed. By default, WindowText is the same string as the Text property. Descendants of TControl can override the Text property to implement a different value. For an edit box, the WindowText is the content of the control. For a combo box, the text string is the content of the edit box part of the combo box. For a button, the string is the button name. For all other controls, the string is the window title.


TControl events

TControl	Alphabetically	Legend

In TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TControl events

TControl	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TControl::OnClick

TControl	See also	Example

Occurs when the user clicks the control.

__property Classes::TNotifyEvent OnClick = {read=FOnClick, write=FOnClick};

Description

Use the OnClick event handler to write code that responds to the click event.

Usually OnClick occurs because the user presses and releases the primary mouse button with the mouse pointer over the control. This event can also occur when

•	The user selects an item in a grid, outline, list, or combo box by pressing an arrow key.

•	The user presses Spacebar while a button or check box has focus.

•	The user presses Enter when the active form has a default button (specified by the Default property).

•	The user presses Esc when the active form has a cancel button (specified by the Cancel property).

•	The user presses the accelerator key for a button or check box. For example, if the value of the Caption property of a check box is '&Bold', the B is underlined at runtime and the OnClick event of the check box is triggered when the user presses Alt+B.

•	The Checked property of a radio button is set to true.

•	The value of the Checked property of a check box is changed.

•	The Click method of a menu item is called.

For a form, an OnClick event occurs when the user clicks a blank area of the form or on a disabled component.


TControl::OnDblClick

TControl	See also	Example

Occurs when the user double-clicks the primary mouse button when the mouse pointer is over the control.

__property Classes::TNotifyEvent OnDblClick = {read=FOnDblClick, write=FOnDblClick};

Description

Use the OnDblClick event to write code that responds to the double-click event.


TControl::OnDragDrop

TControl	See also 	Example

Occurs when the user drops an object being dragged.

typedef void __fastcall (__closure *TDragDropEvent)(System::TObject* Sender, System::TObject* Source, int X, int Y);

__property TDragDropEvent OnDragDrop = {read=FOnDragDrop, write=FOnDragDrop};

Description

Use the OnDragDrop event handler to specify what you want to happen when the user drops an object. The Source parameter of the OnDragDrop event is the object being dropped, and the Sender is the control the object is being dropped on. The X and Y parameters are the coordinates of the mouse positioned over the control.


TControl::OnDragOver

TControl	See also 	Example

Occurs when the user drags an object over a control.

enum TDragState { dsDragEnter, dsDragLeave, dsDragMove }

typedef void __fastcall (__closure *TDragOverEvent)(System::TObject* Sender, System::TObject* Source, int X, int Y, TDragState State, bool &Accept);

__property TDragOverEvent OnDragOver = {read=FOnDragOver, write=FOnDragOver};

Description

Use an OnDragOver event to signal that the control can accept the dragged object so the user can drop it.

Within the OnDragOver event handler, change the Accept parameter to false to reject the dragged object. Leave Accept as true to allow the user to drop the dragged object on the control.

To change the shape of the cursor, indicating that the control can accept the dragged object if the user drops it, change the value of the DragCursor property for the control before the OnDragOver event occurs.

The Source is the object being dragged, the Sender is the potential drop site, and X and Y are screen coordinates in pixels. The TDragState type specifies the drag state of a dragged control in relationship to another control. These are the possible states:

Value	Meaning

dsDragEnter	The mouse is entering the control.

dsDragMove	The mouse moved while over the control.

dsDragLeave	The mouse is leaving the control.

Note:	Within the OnDragOver event handler, the Accept parameter defaults to true. However, if an OnDragOver event handler is not supplied, the control rejects the dragged object, as if the Accept parameter was changed to false.


TControl::OnEndDrag

TControl	See also 	Example

Occurs when the dragging of an object ends, either by dropping the object or by canceling the dragging.

typedef void __fastcall (__closure *TEndDragEvent)(System::TObject* Sender, System::TObject* Target, int X, int Y);

__property TEndDragEvent OnEndDrag = {read=FOnEndDrag, write=FOnEndDrag};

Description

Use the OnEndDrag event handler to specify any special processing that occurs when dragging stops. The Sender is the object being dragged, Target is the object Sender is dragged to, and X and Y are screen coordinates in pixels.

The OnEndDrag event is received by the Sender. If the dragged object was dropped and accepted by a control, the Target parameter of the OnEndDrag event is set to the object that accepted the drop. If the object was not dropped successfully, the value of Target is NULL.


TControl::OnMouseDown

TControl	See also 	Example

Occurs when the user presses a mouse button with the mouse pointer over a control.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

typedef void __fastcall (__closure *TMouseEvent)(System::TObject* Sender, TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

__property TMouseEvent OnMouseDown = {read=FOnMouseDown, write=FOnMouseDown};

Description

Use the OnMouseDown event handler to implement any special processing that should occur as a result of pressing a mouse button.

The OnMouseDown event handler can respond to left, right, or center mouse button presses and shift key plus mouse-button combinations. Shift keys are the Shift, Ctrl, and Alt keys. X and Y are the pixel coordinates of the mouse pointer in the client area of the Sender.


TControl::OnMouseMove

TControl	See also 	Example

Occurs when the user moves the mouse pointer while the mouse pointer is over a control.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

typedef void __fastcall (__closure *TMouseMoveEvent)(System::TObject* Sender, Classes::TShiftState Shift, int X, int Y);

__property TMouseMoveEvent OnMouseMove = {read=FOnMouseMove, write=FOnMouseMove};

Description

Use the OnMouseMove event handler to make something happen when the mouse pointer moves within the control.

Use the Shift parameter of the OnMouseDown event handler, to respond to the state of the shift keys and mouse buttons. Shift keys are the Shift, Ctrl, and Alt keys or shift key-mouse button combinations. X and Y are pixel coordinates of the new location of the mouse pointer in the client area of the Sender.


TControl::OnMouseUp

TControl	See also 	Example

Occurs when the user releases a mouse button that was pressed with the mouse pointer over a component.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

typedef void __fastcall (__closure *TMouseEvent)(System::TObject* Sender, TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

__property TMouseEvent OnMouseUp = {read=FOnMouseUp, write=FOnMouseUp};

Description

Use the OnMouseUp event handler to implement special processing when the user releases a mouse button.

The OnMouseUp event handler can respond to left, right, or center mouse button presses and shift key plus mouse-button combinations. Shift keys are the Shift, Ctrl, and Alt keys. X and Y are the pixel coordinates of the mouse pointer in the client area of the Sender.


TControl::OnStartDrag

TControl	See also

Occurs when the user has begun to drag the control or an object it contains by left-clicking on the control and holding the mouse button down.

typedef void __fastcall (__closure *TStartDragEvent)(System::TObject* Sender, TDragObject* &DragObject);

__property TStartDragEvent OnStartDrag = {read=FOnStartDrag, write=FOnStartDrag};

Description

Use the OnStartDrag event handler to implement special processing when the user starts to drag the control or an object it contains. Sender is the control that is about to be dragged, or that contains the object about to be dragged.

The OnStartDrag event handler can create a TDragObject object for the DragObject parameter to specify the drag cursor, or, optionally, a drag image list. There is no need to call the Free method for the DragObject when dragging is over.

If the OnStartDrag event handler sets the DragObject parameter to NULL, a TDragControlObject object is automatically created and dragging begins on the control itself.


TControl methods

TControl	Alphabetically	Legend

In TControl

~TControl

BeginDrag

BringToFront

Changed

ChangeScale

Click

ClientToScreen

DblClick

DefaultHandler

DefineProperties

DoEndDrag

DoStartDrag

DragCanceled

DragDrop

Dragging

DragOver

EndDrag

GetClientOrigin

GetClientRect

GetDeviceContext

GetDragImages

GetPalette

GetParentComponent

GetPopupMenu

GetTextBuf

GetTextLen

HasParent

Hide

Invalidate

MouseDown

MouseMove

MouseUp

Notification

PaletteChanged

Perform

ReadState

Refresh

Repaint

RequestAlign

ScreenToClient

SendCancelMode

SendToBack

SetBounds

SetDragMode

SetName

SetParent

SetParentComponent

SetTextBuf

SetZOrder

Show

TControl

Update

UpdateBoundsRect

VisibleChanging

WndProc

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TControl methods

TControl	By object	Legend

~TControl

Assign

BeginDrag

BringToFront

Changed

ChangeScale

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

DblClick

DefaultHandler

DefineProperties

DestroyComponents

Destroying

Dispatch

DoEndDrag

DoStartDrag

DragCanceled

DragDrop

Dragging

DragOver

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetClientOrigin

GetClientRect

GetDeviceContext

GetDragImages

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetPalette

GetParentComponent

GetPopupMenu

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

MouseDown

MouseMove

MouseUp

NewInstance

Notification

PaletteChanged

Perform

ReadState

Refresh

RemoveComponent

Repaint

RequestAlign

SafeCallException

ScreenToClient

SendCancelMode

SendToBack

SetBounds

SetDragMode

SetName

SetParent

SetParentComponent

SetTextBuf

SetZOrder

Show

TControl

Update

UpdateBoundsRect

VisibleChanging

WndProc


TControl::BeginDrag

TControl	See also

Starts the dragging of a control.

void __fastcall BeginDrag(bool Immediate);

Description

Call BeginDrag to control the start of a drag operation. An application needs to call the BeginDrag method to begin dragging only when the DragMode property value for the control is dmManual.

If the Immediate parameter is true, the mouse pointer changes to the value of the DragCursor property and dragging begins immediately. If Immediate is false, the mouse pointer doesn't change to the value of the DragCursor property and dragging doesn't begin until the user moves the mouse pointer a short distance (5 pixels). This allows the control to accept mouse clicks without beginning a drag operation.


TControl::BringToFront

TControl	See also 	Example

Puts the control in front of all other controls in its parent control.

void __fastcall BringToFront(void);

Description

BringToFront is especially useful for making certain that a form is visible. It is also used to reorder overlapping controls within a form.

The order in which controls stack on top of each other (also called the Z order) depends on the order the controls are placed on the form. For example, if you put a label and an image on a form so that one is on top of the other, the one that was placed first on the form becomes the one on the bottom. Because both the label and the image are non-windowed controls, they “stack” as you would expect them to. Call the BringToFront method for the bottom object to make it appear on top.

The stacking order of two windowed controls is the same as the stacking of two non-windowed controls. For example, if you put a memo on a form, then put a check box on top of it, the check box remains on top. Calling BringToFront for the memo moves the memo so that it appears on top.

The stacking order of windowed and non-windowed controls cannot be mingled. For example, if you put a memo, a windowed control, on a form, and then put a label, a non-windowed control, on top of it, the label disappears behind the memo. Windowed controls always stack on top of non-windowed controls. In this example, calling the BringToFront method of the label does nothing, the label remains behind the memo.


TControl::Changed

TControl	See also

Sends a CM_CHANGED message to the control.

void __fastcall Changed(void);

Description

Call Changed after making changes to the properties of the control that affect the properties of a parent object. Changed sends a CM_CHANGED message back to the control. If the control is a windowed control, this message is bubbled up to the parent so that it can make any necessary adjustments.


TControl::ChangeScale

TControl	See also

Repositions and resizes the control by a specified ratio.

DYNAMIC void __fastcall ChangeScale(int M, int D);

Description

Use ChangeScale to rescale a control. ChangeScale modifies the position as well as the size of a control. Thus, ChangeScale modifies the control’s Top, Left, Width, and Height properties.

The M and D parameters define a fraction by which to scale the control. The M parameter is the multiplier and the D parameter is the divisor. For example, to make a control 75% of its original size, specify the value of M as 75, and the value of D as 100 (75/100). Alternately, the same results are achieved by specifying the value of M as 3, and the value of D as 4 (3/4). Both fractions are equal and result in the control being scaled by the same amount, 75%.

To scale the control to be 33% larger than its previous size, specify the value of M as 133, and the value of D as 100 (133/100). Alternately, specify the value of M as 4, and the value of D as 3 (4/3), as the fraction 133/100 is approximately equal to 4/3.

Controls derived from TControl might want to override ChangeScale. For example, a control which defines additional font properties should scale the heights of these fonts by the M/D ratio so that all the control’s fonts scale uniformly. Similarly, any control which subdivides its client area into display regions and displays text in those regions might want to override ChangeScale to ensure those regions resize when the font does.

Note:	Because control sizes and coordinates are integers, scaling them by the M/D ratio incurs some degree of roundoff error. Calling ChangeScale repeatedly means that at some point the control may disappear (when the roundoff errors make the control smaller), or creep off the form (when the roundoff errors move the location of control). When rescaling a control repeatedly, consider destroying and reloading the form after several rescalings so that the coordinates are rescaled without most of the accumulating roundoff error.


TControl::Click

TControl	See also

Generates an OnClick event.

DYNAMIC void __fastcall Click(void);

Description

Click calls any event handler attached to the OnClick event. Override Click to provide other responses in addition to the inherited event-handler call when the user clicks the control.

A control calls Click whenever it receives a left-button mouse-up message (WM_LBUTTONUP) if that message indicates that the mouse up occurred near the corresponding mouse-down. Many specific controls call Click in other circumstances, such as when a user types the shortcut key for a button or menu item.

See the OnClick event for a description of all occurrences that trigger click events.


TControl::ClientToScreen

TControl	See also	Example

Translates a given point from client area coordinates to global screen coordinates.

tagPOINT __fastcall ClientToScreen(const tagPOINT &Point);

Description

Use ClientToScreen to convert a point whose coordinates are expressed locally to the control to the corresponding point in screen coordinates. In client area coordinates (0, 0) corresponds to the upper left corner of the control's client area. In screen coordinates (0, 0) corresponds to the upper left corner of the screen.

Use ScreenToClient along with ClientToScreen to convert from one control's coordinate system to another control's coordinate system. For example,

P = TargetControl->ScreenToClient(SourceControl->ClientToScreen(P));

converts P from coordinates in SourceControl to coordinates in TargetControl.


TControl::TControl

TControl	See also 	Example

Creates an instance of TControl.

__fastcall virtual TControl(Classes::TComponent* AOwner);

Description

Do not call the TControl constructor directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated control.

After calling the inherited method, TControl initializes the following properties:

•	Color to clWindow.

•	ControlStyle to include csCaptureMouse, csClickEvents, csSetCaption, and csDoubleClick.

•	DragCursor to crDrag.

•	Enabled and Visible to true.

•	IsControl to false.

•	ParentColor, ParentFont, and ParentShowHint to true.

Note:	If a component's constructor allocates resources or memory, also override the destructor to free those resources.


TControl::DblClick

TControl	See also

Generates an OnDblClick event.

DYNAMIC void __fastcall DblClick(void);

Description

DblClick calls any event handler attached to the OnDblClick event. Override DblClick to provide other responses in addition to the inherited event-handler call when the user double-clicks the control.

The DblClick method is triggered by a left-button double-click message (WM_LBUTTONDBLCLICK) from Windows.


TControl::DefaultHandler

TControl	See also

Provides message handling for all messages that do not have specific handlers.

virtual void __fastcall DefaultHandler(void *Message);

Description

Override DefaultHandler to extend the default handling of messages. DefaultHandler is the final opportunity for component writers to handle messages to controls. The WndProc method provides the first opportunity. Individual message methods such as Click provide additional opportunities.

DefaultHandler handles the messages Windows sends to manage the control's text: WM_GETTEXT, WM_SETTEXT, and WM_GETTEXTLENGTH.


TControl::DefineProperties

TControl	See also

Makes the IsControl protected property persistent, providing methods to read and write IsControl to a stream, such as a form file.

virtual void __fastcall DefineProperties(Classes::TFiler* Filer);

Description

Override DefineProperties to define new properties or publish unpublished properties. To define a new property, call the DefineBinaryProperty or DefineProperty method of the TFiler object passed as the Filer parameter.

Note:	When overriding this method, call the inherited DefineProperties method first.


TControl::~TControl

TControl	See also

Destroys an instance of TControl.

__fastcall virtual ~TControl(void);

Description

Do not call ~TControl directly in an application. Instead, use the delete keyword which operates on an indirect reference to the control.

Applications should only free controls explicitly when the constructor was called to create an instance of the control without giving it an owner.


TControl::DoEndDrag

TControl	See also

Generates an OnEndDrag event.

DYNAMIC void __fastcall DoEndDrag(System::TObject* Target, int X, int Y);

Description

The DoEndDrag method calls any event handler attached to the OnEndDrag event. When creating a component that descends from TControl, override DoEndDrag to provide other responses in addition to the inherited event-handler call when the user drops an object or cancels a drag-and-drop operation.


TControl::DoStartDrag

TControl	See also

Generates an OnStartDrag event.

DYNAMIC void __fastcall DoStartDrag(TDragObject* &DragObject);

Description

The DoStartDrag method calls any event handler attached to the OnStartDrag event. When creating a component that descends from TControl, override DoStartDrag to provide other responses in addition to the inherited event-handler call when the user starts a drag-and-drop operation.


TControl::DragCanceled

TControl	See also

Provides the interface for a method that responds to the cancellation of a drag.

DYNAMIC void __fastcall DragCanceled(void);

Description

By default, DragCancelled does nothing. When creating a component that descends from TControl, override DragCanceled to provide code that executes when a drag operation is canceled.


TControl::DragDrop

TControl	See also

Generates an OnDragDrop event.

DYNAMIC void __fastcall DragDrop(System::TObject* Source, int X, int Y);

Description

When creating a component that descends from TControl, override DragDrop to add additional code that executes before the OnDragDrop event handler is called.

The Source parameter of the DragDrop method is the object to be considered dropped by the handler. The X and Y parameters are the coordinates of the mouse positioned where the object is to be considered dropped.


TControl::Dragging

TControl	See also	Example

Indicates whether a control is being dragged.

bool __fastcall Dragging(void);

Description

Use Dragging to determine the drag state of the control. If Dragging returns true, the control is being dragged. If Dragging is false, the control is not being dragged.


TControl::DragOver

TControl	See also

Generates an OnDragOver event.

enum TDragState { dsDragEnter, dsDragLeave, dsDragMove }

DYNAMIC void __fastcall DragOver(System::TObject* Source, int X, int Y, TDragState State, bool &Accept);

Description

Override DragOver to add additional code that executes before the OnDragOver event handler is called.

Set the Accept parameter to true, to indicate that the user can drop the dragged object on the control. Set Accept to false, to indicate that the user can’t drop the dragged object on the control.

The Source parameter is the object being dragged. These are the possible values of the State parameter:

Value	Meaning

dsDragEnter	The mouse is entering the control.

dsDragMove	The mouse moved while over the control.

dsDragLeave	The mouse is leaving the control.


TControl::EndDrag

TControl	See also	Example

Stops a control from being dragged any further.

void __fastcall EndDrag(bool Drop);

Description

Use EndDrag to stop a dragging operation that began with a call to the BeginDrag method.

If the Drop parameter is true, the control being dragged is dropped. If the Drop parameter is false, the control is not dropped and dragging is canceled.


TControl::GetClientOrigin

TControl	See also

Returns the screen coordinates of the top-left corner of the control’s client area.

virtual tagPOINT __fastcall GetClientOrigin(void);

Description

Override GetClientOrigin to change how the ClientOrigin is calculated.

The GetClientOrigin method is the protected method for reading the ClientOrigin property. GetClientOrigin calculates the ClientOrigin by adding the control’s Left and Top values to the ClientOrigin coordinates of its parent.


TControl::GetClientRect

TControl	See also

Returns a rectangle defining the client area of the control.

virtual Windows::TRect __fastcall GetClientRect(void);

Description

Override GetClientRect to change how the client area is calculated.

The GetClientRect method is the protected method for reading the ClientRect property. GetClientRect returns a rectangle with the rectangle’s Top and Left fields set to zero, and its Bottom and Right fields set to the control's ClientHeight and ClientWidth, respectively.


TControl::GetDeviceContext

TControl	See also

Returns a device context for the control.

virtual HDC __fastcall GetDeviceContext(HWND &WindowHandle);

Description

Call GetDeviceContext to obtain a device context. Override GetDeviceContext to change how the device context is obtained.

Pass the window handle of the control in the WindowHandle parameter. GetDeviceContext returns the device context returned by its parent control's GetDeviceContext method.


TControl::GetDragImages

TControl	See also

Returns the control's image list containing the image to be displayed while dragging.

virtual TCustomImageList* __fastcall GetDragImages(void);

Description

Override GetDragImages to provide a custom image list for the control. The GetDragImages method for TControl returns NULL.


TControl::GetPalette

TControl	See also

Returns the handle to a palette for use by the control.

DYNAMIC HPALETTE __fastcall GetPalette(void);

Description

The GetPalette for TControl returns a null handle, indicating that the control does not have a palette. Override GetPalette to implement derived objects that use a palette. Create a palette handle for the control by a call to the Windows API function CreatePalette. GetPalette should return the palette handle for the control.

Specifying the palette for a control tells the application that the control's palette needs to be realized and designates the palette to use for realization.

GetPalette is called only if the run-time video mode requires color palette support, for example, in 256-color mode.


TControl::GetParentComponent

TControl	See also

Returns the parent component of the control.

DYNAMIC Classes::TComponent* __fastcall GetParentComponent(void);

Description

Call GetParentComponent to find the parent component of the control. GetParentComponent is a protected access method of the control’s Parent property.


TControl::GetPopupMenu

TControl	See also

Returns the pop-up menu associated with the control.

DYNAMIC Menus::TPopupMenu* __fastcall GetPopupMenu(void);

Description

Call GetPopupMenu to find the popup menu associated with the control. Override GetPopupMenu to change which popup menu is associated with the control or to specify different popup menus depending on the state of the control.

GetPopupMenu returns the value of the Popup property.


TControl::GetTextBuf

TControl	See also 	Example

Retrieves the control's text, copies it into a buffer, and returns the number of characters copied.

int __fastcall GetTextBuf(char * Buffer, int BufSize);

Description

Call GetTextBuf to retrieve the text of a control into a fixed size buffer. The text copied is the value of the Text property. GetTextBuf returns the number of characters that were actually copied, which is either the length of the Text property, or BufSize - 1, whichever is smaller.

To find out how many characters the buffer needs to hold the entire text, call the GetTextLen method before allocating a buffer for GetTextBuf.

Note:	To obtain the control’s text as an AnsiString, use the Text property instead.


TControl::GetTextLen

TControl	See also 	Example

Returns the length of the control's text.

int __fastcall GetTextLen(void);

Description

Call GetTextLen to find the length of the control’s text. This is the size needed for a text buffer to be used by the GetTextBuf method.


TControl::HasParent

TControl	See also

Indicates whether the control has a parent.

DYNAMIC bool __fastcall HasParent(void);

Description

Call HasParent to find out if a control has a parent.

The parent of the control is responsible for writing the control to a stream. By default, HasParent for a control returns true. The parent that writes the control to a stream is usually a form or panel control that contains this control.

Note:	A child control that returns true from HasParent must implement the GetParentComponent and SetParentComponent methods.


TControl::Hide

TControl	See also

Makes the control invisible.

void __fastcall Hide(void);

Description

Call Hide to hide a control. Hide sets the Visible property of the control to false.

Although a control that is hidden is not visible, its properties and methods are still available.


TControl::Invalidate

TControl	See also

Tells Windows to repaint the control after other important Windows messages are handled.

virtual void __fastcall Invalidate(void);

Description

Use Invalidate when the entire control needs to be repainted. When more than one region within the control needs repainting, Invalidate will cause the entire window to be repainted in a single pass, avoiding flicker caused by redundant repaints. There is no performance penalty for calling Invalidate multiple times before the control is actually repainted.


TControl::MouseDown

TControl	See also

Generates an OnMouseDown event.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseDown(TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

Override the protected MouseDown method to provide other responses in addition to calling the OnMouseDown event handler when the user presses the mouse button on the control.

The Button parameter determines which mouse button the user pressed. Shift indicates which shift keys (Shift, Ctrl, or Alt) were down when the user pressed or released the mouse button that generated the mouse-button event. X and Y are the pixel coordinates of the mouse pointer within the client area of the control.

A control calls MouseDown in response to any of the Windows mouse-down messages (WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDOWN), decoding the message parameters into the shift-key state and position, which it passes in the Shift, X, and Y parameters, respectively. The value of the Button parameter depends on which of the Windows messages triggered the event.


TControl::MouseMove

TControl	See also

Generates an OnMouseMove event.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseMove(Classes::TShiftState Shift, int X, int Y);

Description

Override the protected MouseMove method to provide other responses in addition to calling the OnMouseMove event handler when the user moves the mouse.

A control calls MouseMove in response to any of the Windows mouse-move messages (WM_MOUSEMOVE), decoding the message parameters into the shift-key state and position, which it passes in the Shift, X, and Y parameters, respectively.


TControl::MouseUp

TControl	See also

Generates an OnMouseUp event.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseUp(TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

Override the protected MouseUp method to provide other responses in addition to calling the OnMouseUp event handler when the user releases the mouse.

A control calls MouseUp in response to any of the Windows mouse-up messages (WM_LBUTTONUP, WM_MBUTTONUP, WM_RBUTTONUP), decoding the message parameters into the shift-key state and position, which it passes in the Shift, X, and Y parameters, respectively. The value of the Button parameter depends on which of the Windows messages triggered the event.


TControl::Notification

TControl	See also

Responds to notifications that components are being created or destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

Notification allows TControl to update its Popupmenu property when the pop-up menu it refers to is destroyed.

Override the Notification method to respond to notifications that other components are about to be destroyed or have just been created. Use the Notification method to update controls that rely on other objects. Remove references to objects that are going away so that the control does not refer to objects that have been destroyed. For example, data-aware objects override the Notification method to update themselves when their data source is removed. Some objects respond to notifications that other objects of a specific type are being created.  For example, the session component sets the Session property of new data-aware controls to itself when the AutoSessionName property is true.

By default, components pass along the notification to their owned components, if any.


TControl::PaletteChanged

TControl	See also

Responds to changes in the system's palette by realizing the control's palette.

DYNAMIC bool __fastcall PaletteChanged(bool Foreground);

Description

Override PaletteChanged to change how the control responds to Windows notifications that the system palette is changing. TControl responds to these notifications by trying to realize the control’s palette, if any, into the current device context. If the change in the system palette causes the actual value of the control’s palette to change, PaletteChanged will invalidate the control so that it can repaint with the new palette.

Windows paints the active window with a foreground palette, while other windows are forced to use background palettes. Background palettes are approximate matches to the colors specified by the control’s logical palette, given the limitations imposed by implementing the foreground palette. Windows only allows a single foreground palette.

PaletteChanged allows the control to obtain a new realization of its palette when the system palette changes. When ForeGround is true, the form has been activated and the control is specifying the new foreground palette. When ForeGround is false, another application or form has changed the foreground palette, and controls that are sensitive to the available palette should realize new background palettes to best match their logical palettes.

If the control does not have a logical palette to be realized into the current device context, GetPalette will return a handle of 0, and PaletteChanged will return false, indicating that no palette was realized. If GetPalette returns the handle to a logical palette, PaletteChanged will realize this palette into the current device context, and return true.

Note:	PaletteChanged is called only when the runtime video mode requires palette support, such as for 256 color mode, but not 16 million color mode.


TControl::Perform

TControl	See also	Example

Responds as if the control received a specified Windows message.

int __fastcall Perform(Cardinal Msg, int WParam, int LParam);

Description

Call Perform to bypass the Windows message queue and send a message directly to the control’s window procedure.

Perform fills a message record (of type TMessage) with the message ID passed in the Msg parameter, the message parameters passed in WParam and LParam, and a result field of zero. Perform then passes the message record to the WindowProc method for processing.


TControl::ReadState

TControl	See also

Prepares the control for having its properties assigned values read from a stream.

virtual void __fastcall ReadState(Classes::TReader* Reader);

Description

Override ReadState to change the preparations the control makes as it readies itself to have the values of its properties assigned from a stream. For example, a control might destroy temporary internal data structures or objects before new instances are loaded from the stream. Remember to include a call to the inherited method when overriding ReadState.

TControl::ReadState assigns the TReader object’s Parent property to this control’s own Parent property before calling the inherited ReadState method of TComponent. Finally, ReadState synchronizes the Font, Color, and ShowHint properties with the parent control, as indicated by the ParentFont, ParentColor, and ParentShowHint properties, respectively.


TControl::Refresh

TControl	See also

Repaints the control on the screen.

void __fastcall Refresh(void);

Description

Call Refresh method to repaint the control immediately. Refresh calls the Repaint method. Use the Refresh and Repaint methods interchangeably.


TControl::Repaint

TControl	See also

Forces the control to repaint its image on the screen.

virtual void __fastcall Repaint(void);

Description

Call Repaint to force the control to repaint its image immediately. If the ControlStyle property includes csOpaque, the control paints itself directly. Otherwise, the Repaint method calls the Invalidate method and then the Update method so that any visible portions of controls beneath the control will be repainted as well.


TControl::RequestAlign

TControl	See also

Instructs the parent of a control to reposition the control, enforcing its Align property.

DYNAMIC void __fastcall RequestAlign(void);

Description

Applications do not call this protected method. Controls call RequestAlign internally when changes are made to the size or position of the control, so that they remain properly aligned within the parent control.


TControl::ScreenToClient

TControl	See also	Example

Converts the screen coordinates of a specified point on the screen to client coordinates.

tagPOINT __fastcall ScreenToClient(const tagPOINT &Point);

Description

Use ScreenToClient to convert a point in screen coordinates to local, or client area, coordinates. In client area coordinates (0, 0) corresponds to the upper left corner of the control's client area. In screen coordinates (0, 0) corresponds to the upper left corner of the screen.

Use ScreenToClient along with ClientToScreen to convert from one control's coordinate system to another control's coordinate system. For example,

P = TargetControl->ScreenToClient(SourceControl->ClientToScreen(P));

converts P from coordinates in SourceControl to coordinates in TargetControl.


TControl::SendCancelMode

TControl	See also

Cancels the modal state of the control.

void __fastcall SendCancelMode(TControl* Sender);

Description

Call SendCancelMode to cancel the modal state of the control. Various controls implemented in the VCL support a model state where the user must respond to the control before interacting with any other object on the form. An example would be the dropped-down state of a combo box when the drop-down list is showing. For these controls, specific user actions send a windows message to the control to end the model state, such as a mouse click that closes up the dropped-down list.

SendCancelMode allows an application to end the modal state of the control in the absence of a user action, or in order to implement a new user interface response.


TControl::SendToBack

TControl	See also	Example

Puts a windowed control behind all other windowed controls in its parent, or puts a non-windowed control behind all other non-windowed controls in its parent.

void __fastcall SendToBack(void);

Description

Use SendToBack to change the order of overlapping controls or forms.

The order in which controls stack on top of each other (also called the Z order) depends on the order the controls are placed on the form. For example, if you put a label and an image on a form so that one is on top of the other, the one that was placed first on the form becomes the one on the bottom. Because both the label and the image are non-windowed controls, they “stack” as you would expect them to. Call the SendToBack method for the top object to move it below the other object.

The stacking order of two windowed controls is the same as the stacking of two non-windowed controls. For example, if you put a memo on a form, then put a check box on top of it, the check box remains on top. Calling SendToBack for the check box makes the memo appear on top.

The stacking order of windowed and non-windowed controls cannot be mingled. For example, if you put a memo, a windowed control, on a form, and then put a label, a non-windowed control, on top of it, the label disappears behind the memo. Windowed controls always stack on top of non-windowed controls. In this example, calling the SendToBack method of the memo does nothing, the label remains behind the memo.

If the control has the input focus when the SendToBack method executes, it loses the input focus.


TControl::SetBounds

TControl	See also

Sets the Left, Top, Width, and Height properties all at once.

virtual void __fastcall SetBounds(int ALeft, int ATop, int AWidth, int AHeight);

Description

Use SetBounds to change all of the component's boundary properties at one time. The same effect can be achieved by setting the Left, Top, Width, and Height properties separately, but SetBounds changes all four properties at once ensuring that the control will not repaint between changes.

Specify the values for the Left, Top, Width, and Height properties as the value of the ALeft, ATop, AWidth, and AHeight parameters, respectively.


TControl::SetDragMode

TControl	See also

Sets the drag mode for the control.

enum TDragMode { dmManual, dmAutomatic };

virtual void __fastcall SetDragMode(TDragMode Value);

Description

SetDragMode is the protected method for the DragMode property. Override SetDragMode to execute additional code when the value of the DragMode property changes.


TControl::SetName

TControl	See also

Sets the name of the control.

virtual void __fastcall SetName(const System::AnsiString Value);

Description

SetName is the protected method for setting the value of the Name property. Override SetName to execute additional code when the value of the Name property changes.


TControl::SetParent

TControl	See also

Sets the parent of the control.

virtual void __fastcall SetParent(TWinControl* AParent);

Description

Call SetParent to make the specified window control the parent of this control. The SetParent method is a protected method for setting the Parent property. Override SetParent to execute additional code when the value of the Parent property changes.

Specify the control that is to become the parent control as the value of the AParent parameter.

If the control already has a parent, SetParent removes the control from that parent's list of controls by calling the parent's RemoveControl method. If AParent is non-NULL, SetParent calls that control's InsertControl method to add the control to its list of controls.

The destructor of all controls calls SetParent(NULL) to remove the control from its parent's control list before destroying the component.


TControl::SetParentComponent

TControl	See also

Sets the parent for the control.

DYNAMIC void __fastcall SetParentComponent(Classes::TComponent* Value);

Description

Do not call the SetParentComponent method.  It is used by the streaming system that loads and saves VCL components.  SetParentComponent makes the component specified by the Value parameter the parent of the control.

SetParentComponent calls the SetParent method only if the component specified as the parent is a windowed control.


TControl::SetTextBuf

TControl	See also	Example

Sets the text of the control.

void __fastcall SetTextBuf(char* Buffer);

Description

Call the SetTextBuf method to set the text of the control to the text in the specified buffer.

The text is set to the text in the buffer pointed to by the Buffer parameter. Buffer must point to a null-terminated string. The SetTextBuf method sends the WM_SETTEXT and CM_TEXTCHANGED messages.

Note:	To set the control’s text using an AnsiString, use the Text property instead.


TControl::SetZOrder

TControl	See also

Repositions the control in its parent’s control list, thereby changing position onscreen.

DYNAMIC void __fastcall SetZOrder(bool TopMost);

Description

Call SetZOrder to change the Z-order of the control. To make the control the topmost control, specify the TopMost value as true. To make the control the bottommost, set TopMost to false.

After changing the order, SetZOrder invalidates the control to ensure repainting to reflect the new order.

The stacking order of windowed and non-windowed controls cannot be mingled. For example, if you put a memo, a windowed control, on a form, and then put a label, a non-windowed control, on top of it, the label disappears behind the memo. Windowed controls always stack on top of non-windowed controls. In this example, calling the SetZOrder method of the label or the memo has no effect, the label always remains behind the memo.


TControl::Show

TControl	See also

Makes a control visible.

void __fastcall Show(void);

Description

Use the Show method to make visible a control that was previously hidden.

The Show method sets the control’s Visible property to true and also ensures that the parent control is visible.


TControl::Update

TControl	See also

Processes any pending paint messages immediately.

virtual void __fastcall Update(void);

Description

Call Update to force the control to be repainted before any more, possibly time-consuming, processing takes place. Use Update to provide immediate feedback to the user that cannot wait for the Windows paint message to arrive. Update does not invalidate the control, but simply forces a repaint of any regions that have already been invalidated. Call Repaint instead if you need to invalidate the control as well.


TControl::UpdateBoundsRect

TControl	See also

Changes the Top, Left, Width, and Height properties of the control, but doesn’t update its screen image.

void __fastcall UpdateBoundsRect(const Windows::TRect &R);

Description

UpdateBoundsRect is used internally by controls to stay synchronized with changes made by Windows. UpdateBoundsRect updates the properties to match those passed in the rectangle as the R parameter.


TControl::VisibleChanging

TControl	See also

Provides the interface for a method that responds to changes in the control’s visibility.

DYNAMIC void __fastcall VisibleChanging(void);

Description

VisibleChanging is called before the value of a control’s Visible property changes. As implemented in TControl, it does nothing. Override VisibleChanging to respond to changes in the control’s visibility. For example, if a control should not change its visibility, override VisibleChanging to throw an exception when an attempt is made to alter the control’s visibility.


TControl::WndProc

TControl	See also

Provides specific message responses for the control.

1

 WndProc(Messages::TMessage &Message);

Description

Override WndProc to change the initial Windows message handler for the control. The WindowProc property is initialized to WndProc.

WndProc implements the mouse behavior specified by the ControlStyle and DragMode properties, and updates the ControlState property. It passes any unhandled messages on to the Dispatch method.

When overriding WndProc to provide specialized responses to messages, be sure to call the inherited WndProc at the end to dispatch any unhandled messages.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TConversion

Hierarchy	Methods	See also

TConversion converts rich text data from one encoding format to another, at the point when the data is streamed from a storage medium that uses one format to a storage medium that uses the other.

Unit

comctrls

Description

TConversion, by itself, does not perform any conversions. It simply reads from or writes to a stream. TConversion exists primarily to provide an interface that can be overridden by derived classes that convert text from one format to another when it is streamed.

Descendants of TCustomRichEdit use TConversion when streaming text to and from files, when the files contain plain ANSI text or text in rich text format (RTF). To allow rich text edit controls to read from and write to files that use another format, derive a class from TConversion which converts between that format and RTF. Rich text edit controls can use the new class by registering it through their RegisterConversionFormat method, or by making it the default converter.


TConversion methods

TConversion	Alphabetically

In TConversion

~TConversion

ConvertReadStream

ConvertWriteStream

TConversion

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TConversion methods

TConversion	By object

~TConversion

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ConvertReadStream

ConvertWriteStream

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TConversion


TConversion::ConvertReadStream

TConversion	See also

Reads BufSize bytes from Stream into the memory buffer pointed to by Buffer.

virtual int __fastcall ConvertReadStream(Classes::TStream* Stream, char * Buffer, int BufSize);

Description

To convert text between two formats, override this method in a descendent class and convert the text in the buffer. To create a descendent class that TCustomRichEdit can use, convert the text to RTF format.

Note:	ConvertReadStream should reverse the conversion that ConvertWriteStream makes.


TConversion::ConvertWriteStream

TConversion	See also

Writes BufSize bytes to Stream from the memory buffer pointed to by Buffer.

virtual int __fastcall ConvertWriteStream(Classes::TStream* Stream, char * Buffer, int BufSize);

Description

To convert text between two formats, override this method in a descendent class and convert the text in the buffer. To create a descendent class that TCustomRichEdit can use, convert the text from RTF format.

Note:	ConvertWriteStream should reverse the conversion that ConvertReadStream makes.


TConversion::TConversion

TConversion

Creates a new TConversion object.

__fastcall TConversion(void) : System::TObject() { }

Description

Do not call TConversion directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated TConversion object.


TConversion::~TConversion

TConversion

Frees the memory associated with the TConversion object.

__fastcall virtual ~TConversion(void) { }

Description

Do not call ~TConversion directly. Instead, use the delete keyword on the object, which causes ~TConversion to be invoked automatically.


Hierarchy

TObject


TCookie

Hierarchy	Properties	Methods	See also

TCookie represents a Cookie header in an HTTP response message.

Unit

httpapp

Description

Use TCookie to specify the cookie header that should be sent with a response message when responding to an HTTP request message. Cookie headers contain state information that the Web client passes on to other locations on the internet or intranet.


TCookie properties

TCookie	Alphabetically	Legend

In TCookie

Domain

Expires

HeaderValue

Name

Path

Secure

Value

Derived from TCollectionItem

Collection

DisplayName

ID

Index


TCookie properties

TCookie	By object	Legend

Collection

DisplayName

Domain

Expires

HeaderValue

ID

Index

Name

Path

Secure

Value


TCookie::Domain

TCookie	See also

Specifies the Domain field of the cookie header.

__property System::AnsiString Domain = {read=FDomain, write=FDomain};

Description

Use Domain to limit the recipients of the cookie header to certain domains. The Web client will only send this cookie on to URIs in the specified domain.  To limit the recipients to certain paths within the specified domain, use the Path property.


TCookie::Expires

TCookie	See also

Specifies when the cookie is no longer valid.

__property System::TDateTime Expires = {read=FExpires, write=FExpires};

Description

Set Expires to the date and time after which the Web client should not send the cookie on with HTTP messages.


TCookie::HeaderValue

TCookie	See also

Specifies the Cookie header string that represents this TCookie object.

__property System::AnsiString HeaderValue = {read=GetHeaderValue};

Description

Read HeaderValue to determine the Cookie header that is added to the HTTP response message for this TCookie object. HeaderValue combines the information specified by the Name and Value properties into a single Name=Value field, and then adds the Domain, Path, Expires, and Secure fields based on the values of the properties with the corresponding names.


TCookie::Name

TCookie	See also

Specifies the name of the custom field represented by this Cookie header.

__property System::AnsiString Name = {read=FName, write=FName};

Description

Set Name to the name that identifies the use of the Value property in the Cookie header. The Value property is combined with the Name property into a string of the form Name=Value.  This string appears as one of the fields in the Cookie header represented by the HeaderValue property.


TCookie::Path

TCookie	See also

Identifies the paths of URLs to which the Cookie should be sent.

__property System::AnsiString Path = {read=FPath, write=FPath};

Description

Use Path to limit the recipients of the cookie header to certain paths. The Web client will only send this cookie header on to URLs with the specified path.  To limit the recipients to certain domains, use the Domain property.


TCookie::Secure

TCookie

Determines whether the Web client must use a secure connection to pass on the Cookie header.

__property bool Secure = {read=FSecure, write=FSecure, nodefault};

Description

Set Secure to true if the Web client must use a secure connection when sending the Cookie header.  Secure connections are connections where messages may not be stored on any permanent medium such as a back-up tape. If the message is stored temporarily in a file, the file must be deleted.

Set Secure to false if it does not matter whether the Cookie header is sent using a secure connection.


TCookie::Value

TCookie	See also

Specifies the value of the Cookie header field named by the Name property.

__property System::AnsiString Value = {read=FValue, write=FValue};

Description

Set Value to the value associated with the field named by the Name property. The Value property is combined with the Name property into a string of the form Name=Value.  This string appears as one of the fields in the Cookie header represented by the HeaderValue property.


TCookie methods

TCookie	Alphabetically

In TCookie

~TCookie

AssignTo

TCookie

Derived from TCollectionItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCookie methods

TCookie	By object

~TCookie

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCookie


TCookie::AssignTo

TCookie	See also

Copies the properties of the TCookie object to another TCookie object.

virtual void __fastcall AssignTo(Classes::TPersistent* Dest);

Description

Do not call the AssignTo method for TCookie.  Instead, call the Assign method of the destination object.  The Assign method of the destination object calls the AssignTo method if it does not contain code for copying the properties of a TCookie object.  If the destination object is a TCookie object, AssignTo copies the Name, Value, Domain, Path, Expires, and Secure properties so the destination cookie generates the same Cookie header string.


TCookie::TCookie

TCookie	See also

Creates an instance of TCookie.

__fastcall virtual TCookie(Classes::TCollection* Collection);

Description

It is seldom necessary to call the constructor for TCookie directly.  Instead, create TCookie objects indirectly by calling the Add method of TCookieCollection. Applications that must create TCookie objects should use the new keyword.

After calling the parent class’s constructor, TCookie initializes the Expires property to indicate no expiration date.


TCookie::~TCookie

TCookie

Frees the memory associated with the TCookie object.

__fastcall virtual ~TCookie(void) { }

Description

Do not call ~TCookie directly. Instead, use the delete keyword on the object, which causes ~TCookie to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


 TCoolBar

Hierarchy	Properties	Methods	Events	See also

TCoolBar is a container for TCoolBand objects. It displays a collection of windowed controls within movable, resizable bands.

Unit

comctrls

Description

A TCoolBar contains child controls that can be moved and resized independently. Each control resides on an individual band, represented by a TCoolBand object listed in the Bands property. The user positions the controls by dragging the sizing grip to the left of each band.

A TCoolBar can contain objects that do not descend from TWinControl, such as TLabel or TSpeedButton. Only TWinControl descendants, however, appear on resizable bands.

The component represented by TCoolBar is sometimes referred to as a rebar.

Note:	TCoolBar requires version 4::70 or later of COMCTL32.DLL. This file, which usually resides in the WINDOWS\SYSTEM or WINDOWS\SYSTEM32 directory, is required at both design time and runtime. Contact Microsoft for information about deploying COMCTL32.DLL.

Note:	See the demo in ::::\Demos\coolstuf\Webbrows.dpr for an example of using TCoolbar.


TCoolBar properties

TCoolBar	Alphabetically	Legend

In TCoolBar

Align

AutoSize

BandBorderStyle

Bands

Bitmap

FixedOrder

FixedSize

Images

ShowText

Vertical

Derived from TToolWindow

BorderWidth

EdgeBorders

EdgeInner

EdgeOuter

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCoolBar properties

TCoolBar	By object	Legend

Align

AutoSize

BandBorderStyle

Bands

Bitmap

BorderWidth

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

EdgeBorders

EdgeInner

EdgeOuter

Enabled

FixedOrder

FixedSize

Font

Handle

Height

HelpContext

Hint

Images

Left

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

ShowText

TabOrder

TabStop

Tag

Top

VCLComObject

Vertical

Visible

Width

WindowProc


TCoolBar::Align

TCoolBar	See also

Determines the alignment of the TCoolBar component.

enum TAlign { alNone, alTop, alBottom, alLeft, alRight, alClient };

__property TAlign Align  = {read=GetAlign, write=SetAlign, default=1};

Description

Setting Align to alLeft or alRight automatically sets Vertical to true. Setting Align to alTop, alBottom, alClient, or alNone automatically sets Vertical to false. In other respects, Align behaves like the parent class’s property.


TCoolBar::AutoSize

TCoolBar	See also

Determines whether the TCoolBar resizes automatically to accommodate the bands it contains.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=0};

Description

When AutoSize is true, the TCoolBar component changes its width or height to accommodate the size and position of the bands within it. The Vertical property determines which dimension is adjusted: If Vertical is true, the component’s width changes. If Vertical is false, the component’s height changes.


TCoolBar::BandBorderStyle

TCoolBar

Determines the border style of the bands in the TCoolBar.

enum TFormBorderStyle { bsNone, bsSingle, bsSizeable, bsDialog, bsToolWindow, bsSizeToolWin };

typedef TFormBorderStyle TBorderStyle;

__property Forms::TBorderStyle BandBorderStyle = {read=FBandBorderStyle, write=SetBandBorderStyle, default=1};

Description

If BandBorderStyle is bsSingle, each band in the TCoolBar has a single line around it. If BandBorderStyle is bsNone, the bands have no borders.


TCoolBar::Bands

TCoolBar	See also 	Example

Lists the bands (TCoolBands) in the coolbar.

__property TCoolBands* Bands = {read=FBands, write=SetBands};

Description

The Bands property holds a TCoolBands—that is, a collection of TCoolBand objects. At design time, you can add, remove, or modify bands with the Bands editor. To open the Bands editor, select the Bands property in the Object Inspector, then double-click in the Value column to the right or click the ellipsis (...) button.

You can also create bands simply by adding new windowed controls from the palette. When any TWinControl descendant is placed on the form as a child of the TCoolBar, a new band is created for it.


TCoolBar::Bitmap

TCoolBar	See also

Specifies the image that appears behind the bands in the TCoolBar.

__property Graphics::TBitmap* Bitmap = {read=FBitmap, write=SetBitmap};

Description

Bitmap holds a TBitmap object. It determines the image that appears behind the bands in the TCoolBar.

By default, the Bitmap image is positioned relative to the upper left corner of the TCoolBar and covers the client area, where the transparent bands allow it to display without occlusion. This appearance can be modified by setting the FixedBackground, Bitmap, and ParentBitmap properties of TCoolBand.


TCoolBar::FixedOrder

TCoolBar	See also

Determines whether the user can reorder the bands in the TCoolBar.

__property bool FixedOrder = {read=FFixedOrder, write=SetFixedOrder, default=0};

Description

If FixedOrder is set to true, the user can reposition the bands by dragging them with the mouse, but cannot change their order. Bands can still be reordered from the Collection editor at design time, or by changing their Index properties in program code.


TCoolBar::FixedSize

TCoolBar	See also

Determines whether the bands automatically maintain a uniform height (or width).

__property bool FixedSize = {read=FFixedSize, write=SetFixedSize, default=0};

Description

Ordinarily, when Vertical and FixedSize are both false, the height of each TCoolBand is determined by the height of the TWinControl component linked to it. (If there is no TWinControl component linked to a band, its height is determined by the text it contains.) When FixedSize is set to true, the bands are resized so that they all have the same height; increasing the height of the tallest visible band automatically increases the height of all the other bands.

When Vertical is true, these dependencies are switched. As long as FixedSize is false, the width of each TCoolBand is determined by the width of the TWinControl component linked to it. If FixedSize and Vertical are both set to true, the bands maintain the same width; increasing the width of the widest visible band automatically increases the width of all the other bands.


TCoolBar::Images

TCoolBar	See also

Lists images available for bands in the TCoolBar.

__property Controls::TImageList* Images = {read=FImages, write=SetImages};

Description

Images is a list of bitmaps that can be displayed to the left of any band in the TCoolBar.


TCoolBar::ShowText

TCoolBar	See also

Determines whether text is displayed on the bands.

__property bool ShowText = {read=FShowText, write=SetShowText, default=1};

Description

If ShowText is true, the Text string of each TCoolBand is displayed on the band at runtime. If ShowText is false, only the TWinControl linked to the band is displayed.


TCoolBar::Vertical

TCoolBar	See also

Determines whether the bands are arranged vertically or horizontally.

__property bool Vertical = {read=FVertical, write=SetVertical, default=0};

Description

If Vertical is false (the default), the bands in the TCoolBar are oriented horizontally, from left to right and top to bottom. If Vertical is true, the bands are oriented vertically, from top to bottom and left to right.


TCoolBar events

TCoolBar	Alphabetically	Legend

In TCoolBar

OnChange

OnResize

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TCoolBar events

TCoolBar	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnStartDrag


TCoolBar::OnChange

TCoolBar	See also

Occurs when the position or size of a band changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

The OnChange event occurs whenever a TCoolBand’s Break, Index, or Width property is modified at runtime. An OnChange event handler can be used, for example, to record the positions and sizes of the bands in the Windows registry.


TCoolBar::OnResize

TCoolBar

Occurs when the TCoolBar is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

The OnResize event occurs whenever the entire TCoolBar is resized at runtime.


TCoolBar methods

TCoolBar	Alphabetically

In TCoolBar

~TCoolBar

TCoolBar

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCoolBar methods

TCoolBar	By object

~TCoolBar

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCoolBar

Update

UpdateControlState


TCoolBar::TCoolBar

TCoolBar	See also

Creates and initializes a TCoolBar instance.

__fastcall virtual TCoolBar(Classes::TComponent* AOwner);

__fastcall TCoolBar(HWND ParentWindow) : Toolwin::TToolWindow(ParentWindow) { }

Description

Call TCoolBar indirectly, using the new keyword, to create a cool bar at runtime. Cool bars added at design time are created automatically.

Pass a single Component as a parameter to provide the cool bar with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the cool bar in a non-VCL window. This syntax is used when the cool bar is implemented as an ActiveX control that is embedded in a non-VCL window.

TCoolBar generates a TCoolBar object and initializes its properties. If COMCTL32.DLL cannot be found, TCoolBar throws the EComponentError exception.


TCoolBar::~TCoolBar

TCoolBar	See also

Destroys the TCoolBar instance and frees its memory.

__fastcall virtual ~TCoolBar(void);

Description

Do not call ~TCoolBar directly in an application. Instead, use the delete keyword.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TToolWindow


TCoolBand

Hierarchy	Properties	Methods	See also

TCoolBand represents a band within a TCoolBar.

Unit

comctrls

Description

Each TCoolBar uses a TCoolBands to maintain a collection of TCoolBand objects.


TCoolBand properties

TCoolBand	Alphabetically	Legend

In TCoolBand

Bitmap

BorderStyle

Break

Color

Control

FixedBackground

FixedSize

HorizontalOnly

ImageIndex

MinHeight

MinWidth

ParentBitmap

ParentColor

Text

Visible

Width

Derived from TCollectionItem

Collection

DisplayName

ID

Index


TCoolBand properties

TCoolBand	By object	Legend

Bitmap

BorderStyle

Break

Collection

Color

Control

DisplayName

FixedBackground

FixedSize

HorizontalOnly

ID

ImageIndex

Index

MinHeight

MinWidth

ParentBitmap

ParentColor

Text

Visible

Width


TCoolBand::Bitmap

TCoolBand	See also

Specifies the background image displayed on the band.

__property Graphics::TBitmap* Bitmap = {read=FBitmap, write=SetBitmap, stored=IsBitmapStored};

Description

Use the Bitmap property to select the image that appears on the band. The image is repeated so that it covers the band like wallpaper.

Setting the Bitmap property in the Object Inspector automatically sets ParentBitmap to false.


TCoolBand::BorderStyle

TCoolBand

Specifies the border style for the band.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

If BorderStyle is set to the default bsSingle, the band has a single-line border. If BorderStyle is set to bsNone, no border appears around the band.


TCoolBand::Break

TCoolBand

Causes the band to start on a new line.

__property bool Break = {read=FBreak, write=SetBreak, default=1};

Description

If Break is true (the default), the band starts a new line at the left side of the TCoolBar control. If Break is false, the band continues on the same line as its predecessor.


TCoolBand::Color

TCoolBand	See also

Specifies the color of the band.

__property Graphics::TColor Color = {read=FColor, write=SetColor, stored=IsColorStored, default=-2147483633};

Description

Use the Color property to select the color of the band. Setting Color in the Object Inspector automatically sets ParentColor to false.


TCoolBand::Control

TCoolBand

Specifies the control that appears on the band.

__property Controls::TWinControl* Control = {read=FControl, write=SetControl};

Description

The Control property indicates the windowed control that appears on the band. If Control is unassigned, there is no control associated with the band.


TCoolBand::FixedBackground

TCoolBand	See also

Determines whether the background is realigned within the band.

__property bool FixedBackground = {read=FFixedBackground, write=SetFixedBackground, default=1};

Description

If ParentBitmap is true, the band displays the same background as the TCoolBar that owns it. Ordinarly, when FixedBackground is true, that background is continuous over the entire TCoolBar. Setting FixedBackground to false realigns the background within the individual band, so that the TCoolBar’s Bitmap image is positioned relative to the upper left corner of the band.


TCoolBand::FixedSize

TCoolBand	See also

Determines whether the band can be resized at runtime.

__property bool FixedSize = {read=FFixedSize, write=SetFixedSize, default=0};

Description

Setting FixedSize to true prevents the user from resizing the band.


TCoolBand::HorizontalOnly

TCoolBand	See also

Determines whether the band is displayed when the TCoolBar is arranged vertically.

__property bool HorizontalOnly = {read=FHorizontalOnly, write=SetHorizontalOnly, default=0};

Description

If the Vertical property of TCoolBar is true, setting HorizontalOnly to true hides the band. When TCoolBar’s Vertical property is false, HorizontalOnly has no effect.


TCoolBand::ImageIndex

TCoolBand	See also

Determines the image (from the TCoolBar::Images list) that appears on the band.

__property int ImageIndex = {read=FImageIndex, write=SetImageIndex, nodefault};

Description

The Images property of TCoolBar contains a list of bitmaps that can appear to the left of any band in the TCoolBar. To select a bitmap from the list, assign a value to the band’s ImageIndex property.


TCoolBand::MinHeight

TCoolBand	See also

Determines the minimum height for the band.

__property int MinHeight = {read=FMinHeight, write=SetMinHeight, default=25};

Description

The MinHeight property determines the smallest height to which the band can be resized at runtime.


TCoolBand::MinWidth

TCoolBand	See also

Determines the minimum width for the band.

__property int MinWidth = {read=FMinWidth, write=SetMinWidth, default=0};

Description

The MinWidth property determines the smallest width to which the band can be resized at runtime.


TCoolBand::ParentBitmap

TCoolBand	See also

Determines whether the band uses the Bitmap image of the TCoolBar that owns it.

__property bool ParentBitmap = {read=FParentBitmap, write=SetParentBitmap, default=1};

Description

If ParentBitmap is set to true, the band displays the same background image as the TCoolBar it belongs to (determined by the TCoolBar’s Bitmap property). Setting the band’s Bitmap property in the Object Inspector automatically sets ParentBitmap to false.


TCoolBand::ParentColor

TCoolBand	See also

Determines whether the band uses the color of the TCoolBar that owns it.

__property bool ParentColor = {read=FParentColor, write=SetParentColor, default=1};

Description

If ParentColor is true, the band has the same color as the TCoolBar that owns it. Setting the Color property in the Object Inspector automatically sets ParentColor to false.


TCoolBand::Text

TCoolBand	See also 	Example

Specifies the text string that appears on the band and identifies it in the Bands editor.

__property System::AnsiString Text = {read=FText, write=SetText};

Description

Assign a value to Text to create text that appears on the band to the left of the band’s windowed control.


TCoolBand::Visible

TCoolBand

Determines whether the band appears at runtime.

__property bool Visible = {read=GetVisible, write=SetVisible, default=1};

Description

Use the Visible property to control the visibility of the band at runtime. If Visible is true, the band appears on the form; if Visible is false, it does not.


TCoolBand::Width

TCoolBand	See also

Specifies the width of the band.

__property int Width = {read=FWidth, write=SetWidth, nodefault};

Description

The Width property indicates the width of the band, in pixels.


TCoolBand methods

TCoolBand	Alphabetically

In TCoolBand

~TCoolBand

Assign

TCoolBand

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCoolBand methods

TCoolBand	By object

~TCoolBand

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCoolBand


TCoolBand::Assign

TCoolBand	See also

Copies the properties of one band to another.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the Text and Width properties of the source band to the band where Assign is called.


TCoolBand::TCoolBand

TCoolBand

Creates and initializes a TCoolBand instance.

__fastcall virtual TCoolBand(Classes::TCollection* Collection);

Description

Do not call TCoolBand directly. Instead, use the keyword new, which returns an indirect reference to the new TCoolBand object. TCoolBand objects added to forms at design time are created automatically.


TCoolBand::~TCoolBand

TCoolBand

Destroys the TCoolBand and frees its memory.

__fastcall virtual ~TCoolBand(void);

Description

Do not call ~TCoolBand directly. Instead, use the delete keyword on the object, which causes ~TCoolBand to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


TCoolBands

Hierarchy	Properties	Methods	See also

TCoolBands is a container for TCoolBand objects.

Unit

comctrls

Description

Each TCoolBands holds a collection of TCoolBand objects in a TCoolBar. TCoolBands maintains an index of the TCoolBand objects in its Items array. The Count property contains the number of bands in the collection.


TCoolBands properties

TCoolBands	Alphabetically	Legend

In TCoolBands

CoolBar

Items

Derived from TCollection

Count

ItemClass


TCoolBands properties

TCoolBands	By object	Legend

CoolBar

Count

ItemClass

Items


TCoolBands::CoolBar

TCoolBands	See also

Provides access to the TCoolBar component that owns the TCoolBands.

__property TCoolBar* CoolBar = {read=FCoolBar};

Description

The CoolBar property returns the TCoolBar instance to which the TCoolBands belongs.


TCoolBands::Items

TCoolBands	See also 	Example

Provides indexed access to the bands in the TCoolBands.

__property TCoolBand* Items[int Index] = {read=GetItem, write=SetItem};

Description

The value of the Index parameter corresponds to the Index property of TCoolBand. It represents the position of the band in the TCoolBands collection.


TCoolBands methods

TCoolBands	Alphabetically

In TCoolBands

~TCoolBands

TCoolBands

Derived from TCollection

Add

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCoolBands methods

TCoolBands	By object

~TCoolBands

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCoolBands


TCoolBands::TCoolBands

TCoolBands

Creates and initializes a TCoolBands instance.

__fastcall TCoolBands(TCoolBar* CoolBar);

Description

Do not call TCoolBands directly. Instead, use the keyword new, which returns an indirect reference to the new TCoolBands object. TCoolBands objects added to forms at design time are created automatically. TCoolBands generates a TCoolBands instance and initializes its properties.


TCoolBands::~TCoolBands

TCoolBands	See also

Destroys the TCoolBands and frees its memory.

__fastcall virtual ~TCoolBands(void) { }

Description

Do not call ~TCoolBands directly. Instead, use the delete keyword on the object, which causes ~TCoolBands to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


TCustomPageProducer

Hierarchy	Properties	Methods	See also

TCustomPageProducer is the base class for objects that produce a string of HTML commands based on an input template.

Unit

httpapp

Description

Use TCustomPageProducer as a base class when defining an object that converts an HTML template into a string of HTML commands which can be interpreted by a client application such as a Web browser. HTML templates include HTML commands and HTML-transparent tags that are replaced with customized content by the page producer.


TCustomPageProducer properties

TCustomPageProducer	Alphabetically	Legend

In TCustomPageProducer

HTMLDoc

HTMLFile

Derived from TCustomContentProducer

Dispatcher

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomPageProducer properties

TCustomPageProducer	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Dispatcher

HTMLDoc

HTMLFile

Name

Owner

Tag

VCLComObject


TCustomPageProducer::HTMLDoc

TCustomPageProducer	See also

Specifies the HTML template used to generate the value returned by the Content method.

__property Classes::TStrings* HTMLDoc = {read=FHTMLDoc, write=SetHTMLDoc};

Description

Set HTMLDoc to a set of strings that make up the HTML template. Each string is a sequence of one or more HTML commands or HTML-transparent tags. An HTML-transparent tag has the form

A pound sign (#) immediately follows the opening angle bracket (<) with no spaces separating it from the angle bracket. The pound sign identifies the string to the page producer as an HTML-transparent tag. The tag name immediately follows the pound sign with no spaces separating it from the pound sign. The page producer converts the entire HTML-transparent tag into true HTML commands based on the value of the tag name. Following the tag name, the HTML-transparent tag can optionally include parameters that specify details of the conversion to be performed. Each parameter is of the form ParamName=Value, where there is no space between the parameter name, the equals symbol (=) and the value. Each parameter is delimited by white space.

The angle brackets (< >) make the tag transparent to HTML browsers that do not recognize the #TagName construct.

The Content method converts HTMLDoc into a final HTML string by calling the HandleTag method to convert each HTML-transparent tag in HTMLDoc.

Note:	Setting HTMLDoc clears the HTMLFile property.


TCustomPageProducer::HTMLFile

TCustomPageProducer	See also

Specifies the name of a file that contains the HTML template used to generate the value returned by the Content method.

__property System::AnsiString HTMLFile = {read=FHTMLFile, write=SetHTMLFile};

Description

Set HTMLFile to the name of the file that contains an HTML template. The HTML template is a sequence of HTML commands and HTML-transparent tags. An HTML-transparent tag has the form

A pound sign (#) immediately follows the opening angle bracket (<) with no spaces separating it from the angle bracket. The pound sign identifies the string to the page producer as an HTML-transparent tag. The tag name immediately follows the pound sign with no spaces separating it from the pound sign. The page producer converts the entire HTML-transparent tag into true HTML commands based on the value of the tag name. Following the tag name, the HTML-transparent tag can optionally include parameters that specify details of the conversion to be performed. Each parameter is of the form ParamName=Value, where there is no space between the parameter name, the equals symbol (=) and the value. Each parameter is delimited by white space.

The angle brackets (< >) make the tag transparent to HTML browsers that do not recognize the #TagName construct.

The Content method converts the HTML template into a final HTML string by calling the HandleTag method to convert each HTML-transparent tag in HTMLFile.

Note:	Setting HTMLFile clears the HTMLDoc property.

Note:	When distributing applications that contain page producers which use the HTMLFile property, be sure to distribute the file along with the application. Also, be sure that the value of HTMLFile does not include a hard-coded path name that will not be available on the user’s disk.


TCustomPageProducer methods

TCustomPageProducer	Alphabetically	Legend

In TCustomPageProducer

~TCustomPageProducer

Content

ContentFromStream

ContentFromString

HandleTag

TCustomPageProducer

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomPageProducer methods

TCustomPageProducer	By object	Legend

~TCustomPageProducer

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Content

ContentFromStream

ContentFromString

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HandleTag

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TCustomPageProducer


TCustomPageProducer::Content

TCustomPageProducer	See also

Returns the HTML code produced by the HTML page producer.

virtual System::AnsiString __fastcall Content(void);

Description

Call Content to get the HTML commands that result from converting the HTML template. Content reads the template from HTMLDoc or HTMLFile, depending on which property is set. Content replaces each HTML-transparent tag in the HTML template with the code returned by the HandleTag method.


TCustomPageProducer::ContentFromStream

TCustomPageProducer	See also

Returns the HTML code that results from converting an HTML template that is read from a stream.

virtual System::AnsiString __fastcall ContentFromStream(Classes::TStream* Stream);

Description

Call ContentFromStream to convert an HTML template that can be read from a stream. The HTML template is a sequence of HTML commands and HTML-transparent tags. ContentFromStream replaces each HTML-transparent tag in the HTML template read from the stream with a string returned by the HandleTag method.


TCustomPageProducer::ContentFromString

TCustomPageProducer	See also

Returns the HTML code that results from converting the string S.

virtual System::AnsiString __fastcall ContentFromString(const System::AnsiString S);

Description

Call ContentFromString to convert a string that consists of an HTML template. An HTML template is a sequence of HTML commands and HTML-transparent tags. ContentFromString replaces each HTML-transparent tag in the HTML template with a string returned by the HandleTag method.


TCustomPageProducer::TCustomPageProducer

TCustomPageProducer	See also

Creates an instance of TCustomPageProducer.

__fastcall virtual TCustomPageProducer(Classes::TComponent* AOwner);

Description

Do not create instances of  TCustomPageProducer. Instead, instantiate a descendant of TCustomPageProducer such as TPageProducer.

After calling the parent object's constructor, TCustomPageProducer allocates the TStrings object that implements the HTMLDoc property.


TCustomPageProducer::~TCustomPageProducer

TCustomPageProducer	See also

Destroys an instance of TCustomPageProducer.

__fastcall virtual ~TCustomPageProducer(void);

Description

Do not call ~TCustomPageProducer directly in an application. Instead, use the delete keyword that operates on an indirect reference to the page producer.

~TCustomPageProducer frees the TStrings object implements the HTMLDoc property before calling the parent object's destructor.


TCustomPageProducer::HandleTag

TCustomPageProducer	See also

Converts an HTML-transparent tag into one or more HTML commands or HTML-transparent tags.

virtual System::AnsiString __fastcall HandleTag(const System::AnsiString TagString, Classes::TStrings* TagParams);

Description

Applications can’t call this protected method directly. HandleTag is called by the Content method, the ContentFromStream method, or the ContentFromString method to convert the HTML-transparent tags in an HTML template. Each HTML-transparent tag has the form

A pound sign (#) immediately follows the opening angle bracket (<) with no spaces separating it from the angle bracket. The tag name immediately follows the pound sign with no spaces separating it from the pound sign. Following the tag name, the HTML-transparent tag can optionally include parameters that specify details of the conversion to be performed. Each parameter is of the form ParamName=Value, where there is no space between the parameter name, the equals symbol (=) and the value. Each parameter is delimited by white space.

The TagString parameter is the tag name portion of the HTML-transparent tag with the pound sign stripped off. The TagParams parameter is the parameter portion of the HTML-transparent tag. HandleTag returns the HTML-transparent tag with the parameters stripped off. The string returned from HandleTag will be ignored by Web browsers that read the resulting HTML.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TCustomContentProducer


TCriticalSection

Hierarchy	Methods	See also

TCriticalSection allows a single thread in a multi-threaded application to temporarily block the execution of all cooperating threads.

Unit

syncobjs

Description

Use TCriticalSection to safeguard operations that may be disrupted if another thread executes before the operation is completed. Critical sections work like gates that allow only a single thread to enter at a time. Because they block the execution of all other threads, overusing critical sections can seriously interfere with performance.

Critical sections must be global in scope so that they are available to all threads. In every thread, any action that could interfere with the operations safeguarded by the critical section should only take place after calling the Acquire or Enter method.  Threads that do not use the critical section for relevent operations can introduce bugs.


TCriticalSection methods

TCriticalSection	Alphabetically

In TCriticalSection

~TCriticalSection

Acquire

Enter

Leave

Release

TCriticalSection

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCriticalSection methods

TCriticalSection	By object

~TCriticalSection

Acquire

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Enter

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

Leave

MethodAddress

MethodName

NewInstance

Release

SafeCallException

TCriticalSection


TCriticalSection::Acquire

TCriticalSection	See also

Binds the critical section to the calling thread.

virtual void __fastcall Acquire(void);

Description

Call Acquire to block all other threads from acquiring this critical section until the Release or Leave method is called. Acquire does the same thing as the Enter method.


TCriticalSection::TCriticalSection

TCriticalSection	See also

Creates an instance of TCriticalSection.

__fastcall TCriticalSection(void);

Description

Call TCriticalSection indirectly, using the new keyword, to create and initialize an instance of TCriticalSection. A TCriticalSection object can be created for a single object that contains thread-sensitive code, or as a global object to be shared by several threads.


TCriticalSection::~TCriticalSection

TCriticalSection	See also

Destroys an instance of TCriticalSection.

__fastcall virtual ~TCriticalSection(void);

Description

Do not call ~TCriticalSection directly in an application. Instead, use the delete keyword.


TCriticalSection::Enter

TCriticalSection	See also

Blocks other threads when the calling thread enters a thread-sensitive section.

void __fastcall Enter(void);

Description

Call Enter to block all other threads from entering code protected by this critical section until the Leave or Release method is called. Enter calls the Acquire method to bind the critical section to the calling thread.


TCriticalSection::Leave

TCriticalSection	See also

Allows other threads to use the critical section.

void __fastcall Leave(void);

Description

Call Leave at the end of a thread-sensitive section of code. Each call to Leave should be balanced by a call to Enter or Acquire at the beginning of the thread-sensitive section. Leave calls Release to allow other threads to acquire the critical section.


TCriticalSection::Release

TCriticalSection	See also

Allows other threads to use the critical section.

virtual void __fastcall Release(void);

Description

Call Release when the thread no longer needs to block other threads from executing code that is protected by this critical section. Each call to Release should be balance by an earlier call to Acquire or Enter that blocked other threads from executing. Release does the same thing as the Leave method.


Hierarchy

TObject

TSynchroObject


TCurrencyField

Hierarchy	Properties	Methods	Events	See also

TCurrencyField represents a field that contains currency values in a dataset.

Unit

db

Description

Currency fields can hold values in the range from (positive or negative) 5::0 * 10-324 to 1::7 * 10308 with an accuracy of 15 digits.

TCurrencyField differs from its immediate ancestor TFloatField only in having a DataType of ftCurrency, and in formatting the value using a currency format by default. As a descendant of TFloatField, TCurrencyField includes many properties, methods, and events that are useful for managing the value and properties of a floating-point field in a database.

Do not confuse TCurrencyField with the Currency data type. Currency fields use the Double data type to store and manipulate their values. This data type is the format used by the physical database tables for currency fields. The TBCDField class uses the Currency data type to store and manipulate its value.


TCurrencyField properties

TCurrencyField	Alphabetically	Legend

Derived from TFloatField

AsFloat

AsInteger

AsString

AsVariant

Currency

DataSize

MaxValue

MinValue

Precision

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCurrencyField properties

TCurrencyField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

Currency

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

Precision

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TCurrencyField events

TCurrencyField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TCurrencyField events

TCurrencyField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TCurrencyField methods

TCurrencyField	Alphabetically

In TCurrencyField

~TCurrencyField

TCurrencyField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCurrencyField methods

TCurrencyField	By object

~TCurrencyField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TCurrencyField

Validate


TCurrencyField::TCurrencyField

TCurrencyField	See also

Creates an instance of TCurrencyField.

__fastcall virtual TCurrencyField(Classes::TComponent* AOwner);

Description

Do not call TCurrencyField directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated currency field. It is seldom necessary to explicitly create a currency field, because currency field objects are instantiated automatically for all currency fields in a dataset.

After calling the parent object's constructor, TCurrencyField sets the DataType to ftCurrency, and the Currency property to true.


TCurrencyField::~TCurrencyField

TCurrencyField

Frees the memory associated with the TCurrencyField object.

__fastcall virtual ~TCurrencyField(void) { }

Description

Do not call ~TCurrencyField directly. Instead, use the delete keyword on the object, which causes ~TCurrencyField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField

TFloatField


TCustomServerSocket

Hierarchy	Properties	Methods	Events	See also

TCustomServerSocket is the base class for all server socket components.

Unit

scktcomp

Description

TCustomServerSocket introduces new properties and events specific to the functions of a TCP/IP server.

Do not create instances of TCustomServerSocket. Use TCustomServerSocket as a base class when declaring server socket objects that listen for connection requests from other machines. To create a socket that responds to requests for connections from other machines, use TServerSocket. To create a socket that converts client messages into COM invocations, use TSocketDispatcher.


TCustomServerSocket properties

TCustomServerSocket	Alphabetically	Legend

In TCustomServerSocket

ServerType

ThreadCacheSize

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomServerSocket properties

TCustomServerSocket	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

ServerType

Tag

ThreadCacheSize

VCLComObject


TCustomServerSocket::ServerType

TCustomServerSocket	See also

Specifies whether each connection accepted by the server socket is non-blocking, or if it is automatically given a separate execution thread.

enum TServerType { stNonBlocking, stThreadBlocking };

__property TServerType ServerType = {read=FServerType, write=SetServerType, nodefault};

Description

Set ServerType to stThreadBlocking to automatically spawn a new thread for each socket connection accepted by the server socket. When ServerType is stThreadBlocking, the execution of the connection thread is suspended while reading or writing until all information has been transferred over the connection. The thread for each connection generates OnClientRead or OnClientWrite events when the server socket needs to read or write.

Set ServerType to stNonBlocking to handle all reading and writing over the socket connections asynchronously. When ServerType is stNonBlocking, all client connections are handled in a single execution thread by default. OnClientRead or OnClientWrite events occur when the client socket on the other end of one of the connections tries to send or receive information over the connection.

Use a non-blocking socket when the socket needs to synchronize reading and writing with client sockets.

Note:	When ServerType is stThreadBlocking, it is important that the OnClient... event handlers contain thread-safe code.


TCustomServerSocket::ThreadCacheSize

TCustomServerSocket	See also

Specifies the maximum number of threads that can be reused for new client connections.

__property int ThreadCacheSize = {read=FThreadCacheSize, write=SetThreadCacheSize, nodefault};

Description

When ServerType is stThreadBlocking, each new connection that is accepted by the server socket is given a separate execution thread. In order to improve performance, server sockets store the these threads in a cache rather than freeing them when the connection is closed. New connections can then reuse threads from the cache, rather than requiring the socket server to create a new thread every time a connection is accepted.

Set ThreadCacheSize to specify the number of threads that are cached for re-use. The ideal value for ThreadCacheSize depends on the number and frequency of client socket requests received by the server socket. If ThreadCacheSize is too low, the server socket will spend more time freeing and creating threads when client connections are accepted. If ThreadCacheSize is too high, the server socket may unnecessarily lock up the memory for threads that are never reused.


TCustomServerSocket events

TCustomServerSocket	Alphabetically	Legend

In TCustomServerSocket

OnClientConnect

OnClientDisconnect

OnClientError

OnClientRead

OnClientWrite

OnGetSocket

OnGetThread

OnThreadEnd

OnThreadStart


TCustomServerSocket events

TCustomServerSocket	By object	Legend

OnClientConnect

OnClientDisconnect

OnClientError

OnClientRead

OnClientWrite

OnGetSocket

OnGetThread

OnThreadEnd

OnThreadStart


TCustomServerSocket::OnClientConnect

TCustomServerSocket	See also

Occurs when a client socket completes a connection accepted by the server socket.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnClientConnect = {read=FOnClientConnect, write=FOnClientConnect};

Description

Write an OnClientConnect event handler to take specific action when a client socket completes the socket connection to the server socket. For example, the socket may start reading or writing over the connection in an OnClientConnect event handler.

The order of server socket events leading up to OnClientConnect is as follows:

1	An OnListen event occurs just before the server socket is opened for listening.

2	The server socket receives client requests in a listening queue. The server socket accepts one of those requests, and receives a Windows socket handle for the new socket connection.

3	The server socket generates an OnGetSocket event, passing in the Windows socket handle. If a TServerClientWinSocket object for the server endpoint of the new connection is not created in an OnGetSocket event handler, the server socket creates one. The TServerWinSocket object continues to listen for other clients.

4	An OnAccept event occurs, using the new TServerClientWinSocket object.

5	If ServerType is stThreadBlocking and no thread is available in the cache, an OnGetThread event occurs. If the OnGetThread event handler does not create a thread, the server socket creates a TServerClientThread.

6	If ServerType is stThreadBlocking, an OnThreadStart event occurs as the thread begins execution.

7	The client completes the connection to the TServerClientWinSocket object and an OnClientConnect event occurs.

The Sender parameter is the TServerWinSocket object that describes the server endpoint of the listening connection. The Socket parameter is the TServerClientWinSocket object that describes the server endpoint of the connection to the client socket.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientConnect event handler is thread-safe. Use the GetClientThread method of the Sender parameter to access thread-specific information.

Note:	The OnClientConnect event handler for TServerSocket is also set when setting the OnClientConnect event handler of the associated TServerWinSocket.


TCustomServerSocket::OnClientDisconnect

TCustomServerSocket	See also

Occurs when one of the connections to a client socket is closed.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnClientDisconnect = {read=FOnClientDisconnect, write=FOnClientDisconnect};

Description

Write an OnClientDisconnect event handler to take specific action when the connection to a client socket is ending. The termination of a client connection does not close the server socket. The server socket remains open and listening for client requests on its listening connection.

The TServerClientWinSocket that describes the server endpoint of the client connection is freed after OnClientDisconnect. If ServerType is stThreadBlocking, OnThreadEnd occurs after OnClientDisconnect.

The Sender parameter is the TServerWinClient object that describes the server endpoint of the listening connection. The Socket parameter is the TServerClientWinSocket object that describes the server endpoint of the connection with the client socket that is about to end.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientDisconnect event handler is thread-safe. Use the GetClientThread method of the Sender parameter to access thread-specific information.

Note:	The OnClientDisconnect event handler for TServerSocket is also set when setting the OnClientDisconnect event handler of the associated TServerWinSocket.


TCustomServerSocket::OnClientError

TCustomServerSocket	See also

Occurs when there is a failure in establishing, using, or terminating the socket connection to an individual client socket.

enum TErrorEvent { eeGeneral, eeSend, eeReceive, eeConnect, eeDisconnect, eeAccept };

typedef void __fastcall (__closure *TSocketErrorEvent)(System::TObject* Sender, TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode);

__property TSocketErrorEvent OnClientError = {read=FOnClientError, write=FOnClientError};

Description

Write an OnClientError event handler to respond to errors that arise with a connection to an individual client. Set the ErrorCode parameter to 0 if the OnClientError event handler successfully deals with the error condition to prevent an ESocketError from being thrown.

The Sender parameter is the socket component. The Socket parameter is the TCustomWinSocket object that receives the error notification. The ErrorCode parameter is the error code returned by the Windows socket API call.The ErrorEvent parameter indicates what Socket was attempting to do when the error occurred. It has one of the following values:

Value	Meaning

eeGeneral	The socket received an error message that does not fit into any of the following categories.

eeSend	An error occurred when trying to write to the socket connection.

eeReceive	An error occurred when trying to read from the socket connection.

eeConnect	A client connection request that has already been accepted could not be completed.

eeDisconnect	An error occurred when trying to close a connection.

eeAccept	A problem occurred when trying to accept a client connection request.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientError event handler is thread-safe. Use the GetClientThread method of the Sender parameter to access thread-specific information.

Note:	The OnClientError event handler for TServerSocket is also set when setting the OnClientError event handler of the associated TServerWinSocket.


TCustomServerSocket::OnClientRead

TCustomServerSocket	See also

Occurs when the server socket should read information from a client socket.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnClientRead = {read=FOnClientRead, write=FOnClientRead};

Description

Write an OnClientRead event handler to read from the socket connection. If the ServerType property is stThreadBlocking, use a TWinSocketStream object to prevent problems that arise while reading from causing the execution thread to hang indefinitely. Otherwise, use the methods of the Socket parameter to perform the actual reading.

The Sender parameter is the TServerWinClient object that describes the server endpoint of the listening connection. The Socket parameter is the TServerClientWinSocket object that describes the server endpoint of the connection to the client socket that is sending the information.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientRead event handler is thread-safe. Use the GetClientThread method of the Sender parameter to access thread-specific information.


TCustomServerSocket::OnClientWrite

TCustomServerSocket	See also

Occurs when the server socket should write information to a client socket.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnClientWrite = {read=FOnClientWrite, write=FOnClientWrite};

Description

Write an OnClientWrite event handler to write to the socket connection. If the ServerType property is stThreadBlocking, use a TWinSocketStream object to prevent problems that arise while writing from causing the execution thread to hang indefinitely. Otherwise, use the methods of the Socket parameter to perform the actual writing.

The Sender parameter is the TServerWinClient object that describes the server endpoint of the listening connection. The Socket parameter is the TServerClientWinSocket object that describes the server endpoint of the connection to the client socket that will receive the information.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientWrite event handler is thread-safe. Use the GetClientThread method of the Sender parameter to access thread-specific information.


TCustomServerSocket::OnGetSocket

TCustomServerSocket	See also

Occurs when the server socket needs to create a new TServerClientWinSocket object to represent the server endpoint of a connection to a client socket.

typedef void __fastcall (__closure *TGetSocketEvent)(System::TObject* Sender, int Socket, TServerClientWinSocket* &ClientSocket);

__property TGetSocketEvent OnGetSocket = {read=FOnGetSocket, write=FOnGetSocket};

Description

Write an OnGetSocket event handler to create a specialized descendant of TServerClientWinSocket for the server socket component to use. Return the new TServerClientWinSocket object in the ClientSocket parameter. The Sender parameter is the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::OnGetThread

TCustomServerSocket	See also

Occurs when the server socket needs to create a new execution thread for a connection to a client socket.

typedef void __fastcall (__closure *TGetThreadEvent)(System::TObject* Sender, TServerClientWinSocket* ClientSocket, TServerClientThread* &SocketThread);

__property TGetThreadEvent OnGetThread = {read=FOnGetThread, write=FOnGetThread};

Description

Write an OnGetThread event handler to create a specialized descendant of TServerClientThread for the connection to the client socket. Return the new TServerClientThread object in the SocketThread parameter.

Most applications that use thread-blocking server components will want to provide an OnGetThread event handler and implement a TServerClientThread that handles its own reading and writing in a thread-safe manner rather than relying on the default TServerClientThread which triggers OnClientRead and OnClientWrite events. This is because the OnClientRead and OnClientWrite event handlers reside on the server socket, which is in global memory.

The Sender parameter is the TServerWinSocket object that describes the server endpoint of the listening connection. The ClientSocket parameter is the TServerClientWinSocket object that describes the server endpoint of the connection to the client socket that is about to be formed.


TCustomServerSocket::OnThreadEnd

TCustomServerSocket	See also

Occurs when a client socket connection is terminated and the associated thread finishes execution.

typedef void __fastcall (__closure *TThreadNotifyEvent)(System::TObject* Sender, TServerClientThread* Thread);

__property TThreadNotifyEvent OnThreadEnd = {read=FOnThreadEnd, write=FOnThreadEnd};

Description

Write an OnThreadEnd to take specific action when the thread for a client connection finishes execution. OnThreadEnd occurs after the OnClientDisconnect event.

The Sender parameter is the TServerWinSocket that describes the server endpoint of the listening connection. The Thread parameter is the thread that is finishing up.


TCustomServerSocket::OnThreadStart

TCustomServerSocket	See also

Occurs when the execution thread for a connection to a client socket starts up.

typedef void __fastcall (__closure *TThreadNotifyEvent)(System::TObject* Sender, TServerClientThread* Thread);

__property TThreadNotifyEvent OnThreadStart = {read=FOnThreadStart, write=FOnThreadStart};

Description

Write an OnThreadStart to initialize the TServerClientThread for the connection to a single client socket. The Sender parameter is the TServerWinSocket that describes the server endpoint of the listening connection. The Thread parameter is the thread that is about to start execution.


TCustomServerSocket methods

TCustomServerSocket	Alphabetically	Legend

In TCustomServerSocket

~TCustomServerSocket

GetGetSocketEvent

GetGetThreadEvent

GetOnClientError

GetOnClientEvent

GetOnThreadEnd

GetOnThreadStart

GetServerType

GetThreadCacheSize

SetGetSocketEvent

SetGetThreadEvent

SetOnClientError

SetOnClientEvent

SetOnThreadEnd

SetOnThreadStart

SetServerType

SetThreadCacheSize

TCustomServerSocket

Derived from TAbstractSocket

Close

Open

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomServerSocket methods

TCustomServerSocket	By object	Legend

~TCustomServerSocket

AfterConstruction

Assign

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetGetSocketEvent

GetGetThreadEvent

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetOnClientError

GetOnClientEvent

GetOnThreadEnd

GetOnThreadStart

GetParentComponent

GetServerType

GetThreadCacheSize

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

SafeCallException

SetGetSocketEvent

SetGetThreadEvent

SetOnClientError

SetOnClientEvent

SetOnThreadEnd

SetOnThreadStart

SetServerType

SetThreadCacheSize

TCustomServerSocket


TCustomServerSocket::~TCustomServerSocket

TCustomServerSocket	See also

Destroys an instance of TCustomServerSocket.

__fastcall virtual ~TCustomServerSocket(void);

Description

Do not call ~TCustomServerSocket directly in an application. Instead, use the delete keyword.

~TCustomServerSocket frees the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetGetSocketEvent

TCustomServerSocket	See also

Returns the OnGetSocket event handler.

typedef void __fastcall (__closure *TGetSocketEvent)(System::TObject* Sender, int Socket, TServerClientWinSocket* &ClientSocket);

TGetSocketEvent __fastcall GetGetSocketEvent();

Description

Applications cannot call this protected method. GetGetSocketEvent returns the OnGetSocket event handler of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetGetThreadEvent

TCustomServerSocket	See also

Returns the OnGetThread event handler.

typedef void __fastcall (__closure *TGetThreadEvent)(System::TObject* Sender, TServerClientWinSocket* ClientSocket, TServerClientThread* &SocketThread);

TGetThreadEvent __fastcall GetGetThreadEvent();

Description

Applications cannot call this protected method. GetGetThreadEvent returns the OnGetThread event handler of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetOnClientError

TCustomServerSocket	See also

Returns the OnClientError event handler.

enum TErrorEvent { eeGeneral, eeSend, eeReceive, eeConnect, eeDisconnect, eeAccept };

typedef void __fastcall (__closure *TSocketErrorEvent)(System::TObject* Sender, TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode);

TSocketErrorEvent __fastcall GetOnClientError();

Description

Applications cannot call this protected method. GetOnClientError returns the OnClientError event handler of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetOnClientEvent

TCustomServerSocket	See also

Provides indexed access to the various event handlers that respond to client events.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

TSocketNotifyEvent __fastcall GetOnClientEvent(int Index);

Description

Applications can’t call this protected method. It is used internally to implement the event handlers that respond to client events.


TCustomServerSocket::GetOnThreadEnd

TCustomServerSocket	See also

Returns the OnThreadEnd event handler.

typedef void __fastcall (__closure *TThreadNotifyEvent)(System::TObject* Sender, TServerClientThread* Thread);

TThreadNotifyEvent __fastcall GetOnThreadEnd();

Description

Applications cannot call this protected method. GetOnThreadEnd returns the OnThreadEnd event handler of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetOnThreadStart

TCustomServerSocket	See also

Returns the OnThreadStart event handler.

typedef void __fastcall (__closure *TThreadNotifyEvent)(System::TObject* Sender, TServerClientThread* Thread);

TThreadNotifyEvent __fastcall GetOnThreadStart();

Description

Applications cannot call this protected method. GetOnThreadStart returns the OnThreadStart event handler of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetServerType

TCustomServerSocket	See also

Returns the ServerType property.

enum TServerType { stNonBlocking, stThreadBlocking };

TServerType __fastcall GetServerType(void);

Description

Applications cannot call this protected method. GetServerType returns the value of the ServerType property of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::GetThreadCacheSize

TCustomServerSocket	See also

Returns the value of the ThreadCacheSize property.

int __fastcall GetThreadCacheSize(void);

Description

Applications cannot call this protected method. GetThreadCacheSize returns the value of the ThreadCacheSize property of the TServerWinSocket object that describes the server endpoint of the listening connection.


TCustomServerSocket::SetGetSocketEvent

TCustomServerSocket	See also

Sets the OnGetSocket event handler.

typedef void __fastcall (__closure *TGetSocketEvent)(System::TObject* Sender, int Socket, TServerClientWinSocket* &ClientSocket);

void __fastcall SetGetSocketEvent(TGetSocketEvent &Value);

Description

Applications cannot call this protected method. SetGetSocketEvent sets the OnGetSocket event handler of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their OnGetSocket event.


TCustomServerSocket::SetGetThreadEvent

TCustomServerSocket	See also

Sets the OnGetThread event handler.

typedef void __fastcall (__closure *TGetThreadEvent)(System::TObject* Sender, TServerClientWinSocket* ClientSocket, TServerClientThread* &SocketThread);

void __fastcall SetGetThreadEvent(TGetThreadEvent &Value);

Description

Applications cannot call this protected method. SetGetThreadEvent sets the OnGetThread event handler of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their OnGetThread event.


TCustomServerSocket::SetOnClientError

TCustomServerSocket	See also

Sets the OnClientError event handler.

enum TErrorEvent { eeGeneral, eeSend, eeReceive, eeConnect, eeDisconnect, eeAccept };

typedef void __fastcall (__closure *TSocketErrorEvent)(System::TObject* Sender, TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode);

void __fastcall SetOnClientError(TSocketErrorEvent &Value);

Description

Applications cannot call this protected method. SetOnClientError sets the OnClientError event handler of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their OnClientError event.


TCustomServerSocket::SetOnClientEvent

TCustomServerSocket	See also

Sets the client event handlers of the associated TServerWinSocket object.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

void __fastcall SetOnClientEvent(int Index, TSocketNotifyEvent &Value);

Description

Applications cannot call this protected method. SetOnClientEvent sets the various event handlers that respond to events from the server endpoint of a client connection. Server socket components use TServerWinSocket to implement these events.


TCustomServerSocket::SetOnThreadEnd

TCustomServerSocket	See also

Sets the OnThreadEnd event handler.

typedef void __fastcall (__closure *TThreadNotifyEvent)(System::TObject* Sender, TServerClientThread* Thread);

void __fastcall SetOnThreadEnd(TThreadNotifyEvent &Value);

Description

Applications cannot call this protected method. SetOnThreadEnd sets the OnThreadEnd event handler of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their OnThreadEnd event.


TCustomServerSocket::SetOnThreadStart

TCustomServerSocket	See also

Sets the OnThreadStart event handler.

typedef void __fastcall (__closure *TThreadNotifyEvent)(System::TObject* Sender, TServerClientThread* Thread);

void __fastcall SetOnThreadStart(TThreadNotifyEvent &Value);

Description

Applications cannot call this protected method. SetOnThreadStart sets the OnThreadEnd event handler of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their OnThreadEnd event.


TCustomServerSocket::SetServerType

TCustomServerSocket	See also

Sets the ServerType property.

enum TServerType { stNonBlocking, stThreadBlocking };

void __fastcall SetServerType(TServerType Value);

Description

Applications cannot call this protected method. SetServerType sets the ServerType property of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their ServerType property.


TCustomServerSocket::SetThreadCacheSize

TCustomServerSocket	See also

Sets the ThreadCacheSize property.

void __fastcall SetThreadCacheSize(int Value);

Description

Applications cannot call this protected method. SetThreadCacheSize sets the ThreadCacheSize property of the TServerWinSocket object that describes the server endpoint of the listening connection. Server socket objects use TServerWinSocket to implement their ThreadCacheSize property.


TCustomServerSocket::TCustomServerSocket

TCustomServerSocket

Creates a new TCustomServerSocket object.

__fastcall virtual ~TCustomServerSocket(void);

Description

Do not create instances of TCustomServerSocket. It is only used as a base class for server socket classes.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TAbstractSocket

TCustomSocket


TCustomAdapter

Hierarchy	Properties	Methods	See also

TCustomAdapter is a base class for objects that bind VCL objects to OLE interfaces.

Unit

axctrls

Description

Do not create objects of this class.  Instead, call the GetOleFont procedure to create the binding between a TFont and an OLE font object or GetOlePicture to create the binding between a TPicture and an OLE picture object.


TCustomAdapter properties

TCustomAdapter	Alphabetically	Legend

Derived from TInterfacedObject

RefCount


TCustomAdapter properties

TCustomAdapter	By object	Legend

RefCount


TCustomAdapter methods

TCustomAdapter	Alphabetically

In TCustomAdapter

~TCustomAdapter

TCustomAdapter

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCustomAdapter methods

TCustomAdapter	By object

~TCustomAdapter

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCustomAdapter


TCustomAdapter::TCustomAdapter

TCustomAdapter	See also

Constructs an instance of the custom adapter control.

__fastcall TCustomAdapter(void);

Description

Never create an object of this class, only its descendants, such as TFontAdapter or TPictureAdapter.


TCustomAdapter::~TCustomAdapter

TCustomAdapter	See also

Destroys the custom adapter object.

__fastcall virtual ~TCustomAdapter(void);

Description

Do not call ~TCustomAdapter directly. Instead, use the delete keyword.

~TCustomAdapter frees and disconnects the VCL object from an OLE object.


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject


TCustomStaticText

Hierarchy	Properties	Methods	See also

TCustomStaticText is the abstract base class for TStaticText.

Unit

stdctrls

Description

TCustomStaticText is the base class for TStaticText, a windowed control that displays text on a form. This component functions like TLabel, except that it has a window handle.

TCustomStaticText cannot receive focus or contain other controls.


TCustomStaticText properties

TCustomStaticText	Alphabetically	Legend

In TCustomStaticText

Alignment

AutoSize

BorderStyle

FocusControl

ShowAccelChar

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomStaticText properties

TCustomStaticText	By object	Legend

Align

Alignment

AutoSize

BorderStyle

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

FocusControl

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowAccelChar

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomStaticText::Alignment

TCustomStaticText 	See also

Determines how text is aligned within the component.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

The possible values of Alignment are

Value	Meaning

taLeftJustify	Text is aligned at the left of the control.

taCenter	Text is centered in the control.

taRightJustify	Text is aligned at the right of the control.


TCustomStaticText::Autosize

TCustomStaticText	See also

Determines whether the component is automatically resized to accommodate its text.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=1};

Description

If Autosize is true, the component is automatically resized—at runtime and design time—whenever the font size or Caption text changes.


TCustomStaticText::BorderStyle

TCustomStaticText

Determines the appearance of the control’s border.

enum TStaticBorderStyle { sbsNone, sbsSingle, sbsSunken };

_property TStaticBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=0};

Description

The possible values of BorderStyle are

Value	Meaning

sbsNone	No visible border.

sbsSingle	Single-line border.

sbsSunken	Raised border.


TCustomStaticText::FocusControl

TCustomStaticText	See also

Links the component with another windowed control.

__property Controls::TWinControl* FocusControl = {read=FFocusControl, write=SetFocusControl};

Description

Use the FocusControl property to link the TCustomStaticText instance with another windowed control. If the text of Caption includes an accelerator key, the component specified by FocusControl receives focus when the accelerator is pressed.


TCustomStaticText::ShowAccelChar

TCustomStaticText	See also

Enables accelerator characters.

__property bool ShowAccelChar = {read=FShowAccelChar, write=SetShowAccelChar, default=1};

Description

If ShowAccelChar is true, an ampersand in the component’s Caption text appears as an underline and makes the character after it into an accelerator key. If ShowAccelChar is false, ampersands appear as ampersands.


TCustomStaticText methods

TCustomStaticText	Alphabetically

In TCustomStaticText

~TCustomStaticText

TCustomStaticText

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomStaticText methods

TCustomStaticText	By object

~TCustomStaticText

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomStaticText

Update

UpdateControlState


TCustomStaticText::TCustomStaticText

TCustomStaticText	See also

Creates and initializes a TCustomStaticText instance.

__fastcall virtual TCustomStaticText(Classes::TComponent* AOwner);

__fastcall TCustomStaticText(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not instantiate a TCustomStaticText object. To add a static-text control to a form, create an instance of a TCustomStaticBox descendant using the new keyword.

Pass a single component as a parameter to provide the static-text object with an owner that is responsible for freeing it. This is the most commonly used constructor syntax.

To embed the static-text object in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the static-text object is implemented as an ActiveX control.

TCustomStaticText calls the parent object's constructor method, then initializes the TCustomStaticText instance by adding the following flags to ControlStyle: csCaptureMouse, csClickEvents, csSetCaption, csOpaque, csReplicatable, csDoubleClicks. TCustomStaticText also sets AutoSize and ShowAccelChar to true.


TCustomStaticText::~TCustomStaticText

TCustomStaticText

~TCustomStaticText frees the memory associated with the TCustomStaticText object.

__fastcall virtual ~TCustomStaticText(void) { }

Description

Do not call ~TCustomStaticText directly. Instead, use the delete keyword on the object, which causes ~TCustomStaticText to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TControlScrollBar

Hierarchy	Properties	Methods	See also

TControlScrollBar displays a horizontal or vertical scroll bar.

Unit

forms

Description

Use TControlScrollBar to control the scrollbar in a scrolling windowed control such as TForm or TScrollBox. TControlScrollBar introduces properties that control the size of the scrollable region and the position to which that region is scrolled, and when the scrollbar appears.


TControlScrollBar properties

TControlScrollBar	Alphabetically	Legend

In TControlScrollBar

Increment

Kind

Margin

Position

Range

ScrollPos

Tracking

Visible


TControlScrollBar properties

TControlScrollBar	By object	Legend

Increment

Kind

Margin

Position

Range

ScrollPos

Tracking

Visible


TControlScrollBar::Increment

TControlScrollBar 	Example

Determines how far the display moves when the user clicks one of the small end arrows on the scroll bar.

typedef Word TScrollBarInc;

__property TScrollBarInc Increment = {read=FIncrement, write=FIncrement, default=8};

Description

Use Increment to control how the scrollbar affects the scrollable region of the control. If Increment is set to 1, each click scrolls by one position; if Increment is set to 2, each click scrolls by two positions; and so forth.


TControlScrollBar::Kind

TControlScrollBar

Determines whether the scroll bar is horizontal or vertical.

enum TScrollBarKind { sbHorizontal, sbVertical };

__property TScrollBarKind Kind = {read=FKind, nodefault};

Description

These are the possible values for Kind:

Value	Meaning

sbHorizontal	Scroll bar is horizontal

sbVertical	Scroll bar is vertical


TControlScrollBar::Margin

TControlScrollBar	See also 	Example

Determines when a scroll bar is generated.

__property Word Margin = {read=FMargin, write=FMargin, default=0};

Description

The Margin property determines the minimum number of pixels that must separate each control from the edge of the form or scroll box. At runtime, whenever a visual component is less than Margin pixels from the edge and Visible is set to true, a scroll bar appears.


TControlScrollBar::Position

TControlScrollBar	See also 	Example

Specifies position of the thumb tab on the scroll bar.

__property int Position = {read=FPosition, write=SetPosition, default=0};

Description

Use Position to programatically scroll the client area of the associated control. The value of Position changes at runtime as the user scrolls the scroll bar.


TControlScrollBar::Range

TControlScrollBar	See also 	Example

Determines how far the scrolling region of the associated control can move.

__property int Range = {read=FRange, write=SetRange, stored=IsRangeStored, default=0};

Description

Range represents the virtual size (in pixels) of the associated control’s client area. For example, if the Range of a form’s horizontal scroll bar is set to 500, and the width of the form is 200, the scroll bar’s Position can vary from 0 to 300.

If the Range of a horizontal scroll bar is less than the width of the form or scroll box, no horizontal scroll bar appears. If the Range of a vertical scroll bar is less than the height of the form or scroll box, no vertical scroll bar appears.

The value of Range is set automatically, but can be overriden in the Object Inspector or in program code.


TControlScrollBar::ScrollPos

TControlScrollBar	See also	Example

Indicates the amount the associated control is scrolled.

__property int ScrollPos = {read=GetScrollPos, nodefault};

Description

The read-only ScrollPos property returns the current value of Position.


TControlScrollBar::Tracking

TControlScrollBar	Example

Determines whether the form or scroll box moves before the thumb tab is released.

__property bool Tracking = {read=FTracking, write=FTracking, default=0};

Description

Use Tracking to control whether the scrollbar and associated control repaint while the thumb tab is dragged with the mouse. If Tracking is true, the image moves as the user drags the thumb tab. If Tracking is false, the image remains static until the thumb tab is released.

Repainting while the thumb tab is dragged can provide useful feedback to the user about how far the control has scrolled, but slows performance.


TControlScrollBar::Visible

TControlScrollBar	See also 	Example

Determines whether the scroll bar appears.

__property bool Visible = {read=FVisible, write=SetVisible, default=1};

Description

If Visible is set to true, a scroll bar appears whenever a visual component is less than Margin pixels from the edge of the form or scroll box. If Visible is set to false, the scroll bar is never visible. This is useful, for example, for programatically controlling the scroll position of a form without allowing the user to control the scroll position.


TControlScrollBar methods

TControlScrollBar	Alphabetically

In TControlScrollBar

~TControlScrollBar

Assign

TControlScrollBar

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TControlScrollBar methods

TControlScrollBar	By object

~TControlScrollBar

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TControlScrollBar


TControlScrollBar::Assign

TControlScrollBar	See also

Copies the contents of a TControlScrollBar instance to another TControlScrollBar.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the Visible, Range, Position, and Increment properties of the source object to another TControlScrollBar instance.


TControlScrollBar::TControlScrollBar

TControlScrollBar

TControlScrollBar creates a new TControlScrollBar object.

__fastcall TControlScrollBar(void) : Classes::TPersistent() { }

Description

Do not call TControlScrollBar directly. Instead, use the keyword new, which returns an indirect reference to the new scroll bar.


TControlScrollBar::~TControlScrollBar

TControlScrollBar

~TControlScrollBar frees the memory associated with the TControlScrollBar object.

__fastcall virtual ~TControlScrollBar(void) { }

Description

Do not call ~TControlScrollBar directly. Instead, use the delete keyword on the object, which causes ~TControlScrollBar to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent


TControlCanvas

Hierarchy	Properties	Methods	Events	See also

TControlCanvas is a specialized canvas object associated with a control.

Unit

controls

Description

Use TControlCanvas as a drawing space to render the image of a control. Standard window controls such as edit controls or list boxes do not require a canvas, as they are drawn by Windows.

As a canvas, TControlCanvas provides many properties, events, and methods to aid in the creation of rich images. In addition, TControlCanvas adds properties and methods to interact with a control object, and to manage the device context associated with the control.

TControlCanvas is used by TGraphicControl and TCustomControl to provide services for rendering their images.


TControlCanvas properties

TControlCanvas	Alphabetically	Legend

In TControlCanvas

Control

Derived from TCanvas

Brush

ClipRect

CopyMode

Font

Handle

LockCount

Pen

PenPos

Pixels


TControlCanvas properties

TControlCanvas	By object	Legend

Brush

ClipRect

Control

CopyMode

Font

Handle

LockCount

Pen

PenPos

Pixels


TControlCanvas::Control

TControlCanvas	See also

Specifies the control associated with the control canvas object.

__property TControl* Control = {read=FControl, write=SetControl};

Description

Read Control to gain access to the control associated with the control canvas object. Descendants of TControl that use a control canvas set the Control property to form the association. The control canvas object uses the Control property to get information from its associated control.


TControlCanvas events

TControlCanvas	Alphabetically

Derived from TCanvas

OnChange

OnChanging


TControlCanvas events

TControlCanvas	By object

OnChange

OnChanging


TControlCanvas methods

TControlCanvas	Alphabetically

In TControlCanvas

~TControlCanvas

FreeHandle

TControlCanvas

Derived from TCanvas

Arc

BrushCopy

Chord

CopyRect

Draw

DrawFocusRect

Ellipse

FillRect

FloodFill

FrameRect

LineTo

Lock

MoveTo

Pie

PolyBezier

PolyBezierTo

Polygon

Polyline

Rectangle

Refresh

RoundRect

StretchDraw

TextExtent

TextHeight

TextOut

TextRect

TextWidth

TryLock

Unlock

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TControlCanvas methods

TControlCanvas	By object

~TControlCanvas

Arc

Assign

BrushCopy

Chord

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyRect

DefaultHandler

Dispatch

Draw

DrawFocusRect

Ellipse

FieldAddress

FillRect

FloodFill

FrameRect

Free

FreeHandle

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LineTo

Lock

MethodAddress

MethodName

MoveTo

NewInstance

Pie

PolyBezier

PolyBezierTo

Polygon

Polyline

Rectangle

Refresh

RoundRect

SafeCallException

StretchDraw

TControlCanvas

TextExtent

TextHeight

TextOut

TextRect

TextWidth

TryLock

Unlock


TControlCanvas::~TControlCanvas

TControlCanvas	See also

Destroys an instance of TControlCanvas.

__fastcall virtual ~TControlCanvas(void);

Description

Do not call ~TControlCanvas directly in an application. The controls that use a TControlCanvas object destroy it from their own destructors.

~TControlCanvas releases the handle to a device context (HDC) the control canvas uses before freeing the memory associated with the object.


TControlCanvas::FreeHandle

TControlCanvas	See also

Releases the handle to a device context (HDC) used by the control canvas object.

void __fastcall FreeHandle(void);

Description

Call FreeHandle to free the HDC used by the control canvas. FreeHandle sets the Handle property to NULL. After calling FreeHandle, an HDC will be re-acquired if any of the drawing methods are called.

Note:	Setting the Handle property to NULL does not free the HDC. Set the Handle property to NULL rather than call FreeHandle if the HDC is release by the application.


TControlCanvas::TControlCanvas

TControlCanvas

Creates a new TControlCanvas object.

__fastcall virtual ~TControlCanvas(void);

Description

Do not call TControlCanvas directly in an application. The controls that use a TControlCanvas object create it from their own constructors.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCanvas


TCubeDim

Hierarchy	Properties	Methods	See also

TCubeDim represents an entry in the dimension map of a decision cube.

Unit

mxstore

Description

Use TCubeDim to obtain information about the dimensions or summaries maintained by a decision cube. The decision cube maintains a collection of TCubeDim objects that describe the fields over which the information in the decision cube is summarized and the fields that supply those summarized values. The properties of TCubeDim can be used to change the display names of the dimensions of the decision cube, or to expand or collapse individual dimensions of the multidimensional array of values cached by the decision cube.

TCubeDim introduces properties and methods to allow a decision cube to include date ranges as the values along one of its dimensions.


TCubeDim properties

TCubeDim	Alphabetically	Legend

In TCubeDim

BinData

BinFormat

BinType

Loaded

StartValue

Derived from TDimensionItem

ActiveFlag

BaseName

DerivedFrom

DimensionType

Fieldname

FieldType

Format

Name

Derived from TCollectionItem

Collection

DisplayName

ID

Index


TCubeDim properties

TCubeDim	By object	Legend

ActiveFlag

BaseName

BinData

BinFormat

BinType

Collection

DerivedFrom

DimensionType

DisplayName

Fieldname

FieldType

Format

ID

Index

Loaded

Name

StartValue


TCubeDim::BinData

TCubeDim	See also

Represents information about the implementation of paged dimensions.

__property Mxcommon::TBinData* BinData = {read=FBinData};

Description

Do not use the BinData property. It is used internally to manage paged (permanently drilled) dimensions.


TCubeDim::BinFormat

TCubeDim	See also

Indicates how range values are formatted.

__property System::AnsiString BinFormat = {read=FBinFormat, write=FBinFormat};

Description

Set BinFormat to indicate how the labels for date ranges should appear. Use any standard VCL date and time formatting strings, such as those used with the FormatDateTime function.


TCubeDim::BinType

TCubeDim	See also

Indicates how the values of the field represented by the dimension are grouped.

enum TBinType { binNone, binYear, binQuarter, binMonth, binSet, binCustom };

__property Mxcommon::TBinType BinType = {read=GetBin, write=SetBin, nodefault};

Description

Set BinType to restrict the values that appear along the dimension. BinType can have one of the following values:

Value	Meaning

binNone	All values along the dimension appear.

binYear	Each cell along the dimension represents all field values that represent dates from the same year.

binQuarter	Each cell along the dimension represents all field values that represent dates from the same quarter.

binMonth	Each cell along the dimension represents all field values that represent dates from the same month.

binSet	The dimension is in a paged (permanently drilled) state. The drill-down value of the dimension can be changed, but the dimension can not be opened or closed.

binCustom	binCustom is not currently used but is provided to allow component writers to support other types of ranges.

If BinType is binYear, binQuarter, or binMonth, use the BinFormat property to indicate how the values of the ranges along the dimension should be formatted.

If BinType is binSet, use the StartValue property to specify which value along the dimension is used as the drill-down value. Unlike the drill-down value of a normal dimension, which is part of the pivot state stored by the decision source, the drill-down value of a paged dimension is the only value cached by the decision cube. Changing the drill-down value of paged dimensions causes the decision cube to rebuild its cache, which can be very time-consuming.

Note:	When BinType is binSet, the dimension item consumes considerably less memory in the decision cube.

Note:	Do not set BinType to binYear, binQuarter, or binMonth if the dimension does not represent a date or date-time field.


TCubeDim::Loaded

TCubeDim	See also

Indicates whether the dimension item is currently cached by the decision cube.

__property bool Loaded = {read=GetLoaded, write=SetLoaded, nodefault};

Description

Read Loaded to determine whether the dimension item is currently available through the decision cube. When the ActiveFlag property is diActive, Loaded is always true. When the value of ActiveFlag is diInactive, Loaded is always false. When the value of ActiveFlag is diAsNeeded, use Loaded to determine whether the decision cube has cached the dimension item so that it is available to a decision source.

When Loaded is true, the dimension item consumes memory. When Loaded is false, the dimension item is unavailable.


TCubeDim::StartValue

TCubeDim	See also

Determines how values are grouped along a dimension.

__property System::AnsiString StartValue = {read=FStartValue, write=SetStart};

Description

When the BinType property is binYear, binQuarter, or binMonth, set StartValue to the first date in the first range of the dimension. If the BinType property is binSet, set StartValue to the drill-down value of the dimension.


TCubeDim methods

TCubeDim	Alphabetically

In TCubeDim

~TCubeDim

GetBinValues

IsBinData

TCubeDim

Derived from TDimensionItem

IsDimension

IsSummary

Derived from TCollectionItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCubeDim methods

TCubeDim	By object

~TCubeDim

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetBinValues

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

IsBinData

IsDimension

IsSummary

MethodAddress

MethodName

NewInstance

SafeCallException

TCubeDim


TCubeDim::GetBinValues

TCubeDim	See also

Returns the set of values that are summarized by a single value along a dimension.

System::Variant __fastcall GetBinValues(const System::Variant &Value);

Description

Call GetBinValues to determine the actual values that underlie a single dimension member when the BinType property is not binNone. The Value parameter is the single dimension member that represents a date range or the single value of a paged dimension. The value of Value can be obtained by calling the GetMemberAsVariant method of the decision cube or decision source.

If the BinType property of the dimension is binYear, binQuarter, or binMonth, GetBinValues returns the starting and ending values of the range that includes the Value parameter. If the BinType property is binSet, GetBinValues returns the single drilled value of the dimension.


TCubeDim::IsBinData

TCubeDim	See also

Indicates whether the dimension includes a member for every field value.

bool __fastcall IsBinData(void);

Description

Call IsBinData to determine if the dimension item represents a dimension of the decision cube that groups values into date ranges or represents a paged dimension. IsBinData returns true if the value of the BinType property is not binNone.


TCubeDim::TCubeDim

TCubeDim 	See also

Creates a new TCubeDim object.

__fastcall virtual TCubeDim(Classes::TCollection* Collection);

Description

Do not directly create TCubeDim objects directly. Instead, use the Add method of the TCubeDims object that implements the decision cube’s dimension map.


TCubeDim::~TCubeDim

TCubeDim

~TCubeDim frees the memory associated with the TCubeDim object.

__fastcall virtual ~TCubeDim(void);

Description

Do not call ~TCubeDim directly. Instead, use the delete keyword on the object, which causes ~TCubeDim to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem

TDimensionItem


TCubeDims

Hierarchy	Properties	Methods	See also

TCubeDims is a collection of TCubeDim objects.

Unit

mxstore

Description

Use TCubeDims as the dimension map of a crosstabulated data store. Each TCubeDim object maintained by TCubeDims corresponds to a field from the data set of the crosstabulated data store. Each TCubeDim object can be used as either a dimension (a field over which data is summarized), or a summary (a value summarized over the dimensions).

TCubeDims introduces new properties to handle dimension maps that include date ranges.


TCubeDims properties

TCubeDims	Alphabetically	Legend

In TCubeDims

IsDirty

Items

Derived from TDimensionItems

ActiveDimensionCount

ActiveSummaryCount

DimensionCount

SummaryCount

Derived from TCollection

Count

ItemClass


TCubeDims properties

TCubeDims	By object	Legend

ActiveDimensionCount

ActiveSummaryCount

Count

DimensionCount

IsDirty

ItemClass

Items

SummaryCount


TCubeDims::IsDirty

TCubeDims	See also

Indicates that the fields that correspond to the TCubeDim objects in the Items array have changed.

__property bool IsDirty = {read=GetDirtyFlag, nodefault};

Description

Read IsDirty to determine whether the information cached by the decision cube is valid. When any of the properties of the TCubeDim objects in the Items array change, IsDirty becomes true. When the value of IsDirty is read, IsDirty is reset to false.


TCubeDims::Items

TCubeDims	See also

Lists all dimension items maintained by the TCubeDims object.

__property TCubeDim* Items[int Index] = {read=GetCubeDim, write=SetCubeDim};

Description

Use Items to access individual dimensions or summaries maintained by the TCubeDims object. The first TCubeDim object has an Index of 0, the second has an Index of 1, and so on.

Each TCubeDim object in the Items array represents a field from the data set of a decision cube. Each item represents either a dimension (a field over which data is summarized), or a summary (a value summarized over the dimensions).

Note:	Do not change the Items property. The set of items in the Items array is set automatically to represent the fields from the data set. The properties of individual TCubeDim objects within the Items array may be changed to specify whether they should be cached by the data store, the name to use when displaying them, and so on.


TCubeDims methods

TCubeDims	Alphabetically

In TCubeDims

~TCubeDims

TCubeDims

Derived from TDimensionItems

Add

AddDerivedField

AlreadyExists

Assign

AverageFieldCheck

Derived from TCollection

BeginUpdate

Clear

EndUpdate

FindItemID

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCubeDims methods

TCubeDims	By object

~TCubeDims

Add

AddDerivedField

AlreadyExists

Assign

AverageFieldCheck

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TCubeDims


TCubeDims::TCubeDims

TCubeDims 	See also

Creates a new TCubeDims object.

__fastcall TCubeDims(Classes::TPersistent* FOwner, System::TMetaClass* ItemClass);

Description

Most applications do not need to create instances of TCubeDims. Decision cubes automatically create a TCubeDims object to manage their DimensionMap property. When creating a TCubeDims object, use the new keyword.


TCubeDims::~TCubeDims

TCubeDims

~TCubeDims frees the memory associated with the TCubeDims object.

__fastcall virtual ~TCubeDims(void) { }

Description

Do not call ~TCubeDims directly. Instead, use the delete keyword on the object, which causes ~TCubeDims to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection

TDimensionItems


TCustomWebDispatcher

Hierarchy	Properties	Methods	Events	See also

TCustomWebDispatcher is the abstract base class for Web dispatcher objects.

Unit

httpapp

Description

Add a descendant of TCustomWebDispatcher to a Web application to enable it to respond to HTTP request messages. When a Web application is created, it automatically includes a TWebModule object, which is a descendant of TCustomWebDispatcher. Keep the default Web module, or replace it with another data module that contains a descendant of TCustomWebDispatcher, such as TWebDispatcher.

TCustomWebDispatcher manages the action items that assemble responses to HTTP request messages. When the TWebApplication object receives an HTTP request message, TCustomWebDispatcher passes the request on to the appropriate action item or action items to service the message.

TCustomWebDispatcher also keeps track of information about the current HTTP message for the benefit of TCustomContentProducer objects.


TCustomWebDispatcher properties

TCustomWebDispatcher	Alphabetically	Legend

In TCustomWebDispatcher

Action

Actions

Request

Response

Derived from TDataModule

DesignOffset

DesignSize

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomWebDispatcher properties

TCustomWebDispatcher	By object	Legend

Action

Actions

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

DesignOffset

DesignSize

Name

Owner

Request

Response

Tag

VCLComObject


TCustomWebDispatcher::Action

TCustomWebDispatcher	See also

Provides indexed access to the action items managed by the TCustomWebDispatcher object.

__property TWebActionItem* Action[int Index] = {read=GetAction};

Description

Use Action to iterate over all of the actions in the Actions collection. Zero is the index of the first action item, one is the index of the second action item, and so on. To access individual actions by name, use the ActionByName method.


TCustomWebDispatcher::Actions

TCustomWebDispatcher	See also

Represents the collection of action items managed by the TCustomWebDispatcher object.

__property TWebActionItems* Actions = {read=FActions, write=SetActions};

Description

Use the methods of Actions to add action items for use by the dispatcher, to clear the set of action items managed by the dispatcher, or to access the attributes of the action items.


TCustomWebDispatcher::Request

TCustomWebDispatcher	See also

Provides access to the TWebRequest object that the dispatcher is currently handling.

__property TWebRequest* Request = {read=FRequest};

Description

Use Request to obtain information about the current HTTP request message. The dispatcher matches this TWebRequest object to an action item, and invokes the OnAction event handler of the action item to generate and send a response to the HTTP request message. OnAction event handlers often use descendants of TCustomContentProducer to help generate the response to the request message. These content producers can use the Request property to correctly produce the content of the HTTP response.


TCustomWebDispatcher::Response

TCustomWebDispatcher	See also

Provides access to the TWebResponse object for the message the dispatcher is currently handling.

__property TWebResponse* Response = {read=FResponse};

Description

Use Response to obtain information about the emerging response to the current HTTP request message. The dispatcher matches the request object specified by the Request property to an action item. It then invokes the OnAction event handler of the action item to fill in the TWebResponse object specified by the Response property. OnAction event handlers often use descendants of TCustomContentProducer to help generate the response. These content producers can use Response to determine the state of the emerging response that is being produced.


TCustomWebDispatcher events

TCustomWebDispatcher	Alphabetically	Legend

In TCustomWebDispatcher

AfterDispatch

BeforeDispatch

Derived from TDataModule

OnCreate

OnDestroy


TCustomWebDispatcher events

TCustomWebDispatcher	By object	Legend

AfterDispatch

BeforeDispatch

OnCreate

OnDestroy


TCustomWebDispatcher::AfterDispatch

TCustomWebDispatcher	See also

Occurs after the HTTP response message has been successfully filled out by the action items but not yet sent.

typedef void __fastcall (__closure *THTTPMethodEvent)(System::TObject* Sender, TWebRequest* Request, TWebResponse* Response, bool &Handled);

__property THTTPMethodEvent AfterDispatch = {read=FAfterDispatch, write=FAfterDispatch};

Description

Write an AfterDispatch event handler to provide a final check of the HTTP response message before it is sent to the Web client. An AfterDispatch event handler can let a response stand as is, change the response, send the response, or change the Handled parameter to false to prevent the Web application from sending the response.

The AfterDispatch event does not occur if all of the action items indicate that the response was not handled, or if the response is sent by any of the action items.


TCustomWebDispatcher::BeforeDispatch

TCustomWebDispatcher	See also

Occurs before the dispatcher tries to match the HTTP request message with any of its action items.

typedef void __fastcall (__closure *THTTPMethodEvent)(System::TObject* Sender, TWebRequest* Request, TWebResponse* Response, bool &Handled);

__property THTTPMethodEvent BeforeDispatch = {read=FBeforeDispatch, write=FBeforeDispatch};

Description

Write a BeforeDispatch event handler to preprocess all HTTP request messages. A BeforeDispatch event handler can enable or disable the action items appropriate to the response, begin filling out the response object, or provide any other necessary preprocessing.

If the BeforeDispatch event handler finishes filling out the response object, it should change the Handled parameter to true so the dispatcher will not send the request on to any of the action items. If the BeforeDispatch event handler sends the response message, the dispatcher will not pass the request on to any of the action items, even if the Handled parameter is left as false.

If the BeforeDispatch event handler sets the Handled parameter to true but does not send the response, the Web dispatcher will generate an AfterDispatch event.


TCustomWebDispatcher methods

TCustomWebDispatcher	Alphabetically	Legend

In TCustomWebDispatcher

~TCustomWebDispatcher

ActionByName

DispatchAction

DoAfterDispatch

DoBeforeDispatch

Notification

TCustomWebDispatcher

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomWebDispatcher methods

TCustomWebDispatcher	By object	Legend

~TCustomWebDispatcher

ActionByName

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

DispatchAction

DoAfterDispatch

DoBeforeDispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Notification

RemoveComponent

SafeCallException

TCustomWebDispatcher


TCustomWebDispatcher::ActionByName

TCustomWebDispatcher	See also

Returns the action item identified by the AName parameter.

TWebActionItem* __fastcall ActionByName(const System::AnsiString AName);

Description

Call ActionByName to gain access to an individual action item when its name is known. Change the properties of the action item so that it handles different HTTP request messages, or invoke its OnAction event handler to respond to an HTTP request message.


TCustomWebDispatcher::TCustomWebDispatcher

TCustomWebDispatcher	See also

Creates an instance of TCustomWebDispatcher.

__fastcall virtual TCustomWebDispatcher(Classes::TComponent* AOwner);

__fastcall TCustomWebDispatcher(Classes::TComponent* AOwner, int Dummy): Forms::TDataModule(AOwner, Dummy) { }

Description

Do not call the constructor for TCustomWebDispatcher. Web applications automatically include a Web module. If the Web module is replaced by another data model, the Web dispatcher should be added to the new data module at design time. Objects placed at design time are created automatically. If an application tries to create a dispatcher object in a Web module, or in a data module that already has a Web dispatcher, an exception is thrown.

TCustomWebDispatcher creates the TWebActionItems object that holds the action items managed by the dispatcher. If the Web dispatcher is included in another data module, it adds a reference to itself to any content producer in that data module.

After the Web dispatcher is created automatically at runtime, an OnCreate event occurs.


TCustomWebDispatcher::~TCustomWebDispatcher

TCustomWebDispatcher	See also

Frees an instance of TCustomWebDispatcher.

__fastcall virtual ~TCustomWebDispatcher(void);

Description

Do not destroy the TCustomWebDispatcher directly in an application. The dispatcher is freed automatically when the server application shuts down.

~TCustomWebDispatcher frees the TWebActionItems object used to hold the collection of action items.


TCustomWebDispatcher::DispatchAction

TCustomWebDispatcher	See also

Passes an HTTP request message to the action items in Actions until it is handled.

bool __fastcall DispatchAction(TWebRequest* Request, TWebResponse* Response);

Description

The Web application calls DispatchAction when it receives an HTTP request message so that the dispatcher can dispatch the request to any action items that can generate the response.

Before DispatchAction looks for action items to handle the HTTP request message represented by the Request parameter, it generates a BeforeDispatch event. If the BeforeDispatch event handler handles the action, the dispatcher does not pass the request message to any of the action items.

If there is no BeforeDispatch event handler, or of the BeforeDispatch event handler does not handle the request, DispatchAction attempts to match the MethodType and PathInfo of the request with the MethodType and PathInfo properties of each action item in the Actions property. When an action item matches the MethodType and PathInfo of the request, DispatchAction calls its OnAction event handler.

The OnAction event handler can complete the response to the request, or indicate that the request is not fully handled and allow another action item to finish processing the request. If the OnAction event handler does not complete the request, DispatchAction continues checking the action items in the Actions property and calling the OnAction event handler when a match is found.

If all of the action items are checked, and the request is still not fully handled, DispatchAction calls the OnAction event handler of the default action item.

Finally, if the request has been handled by the BeforeDispatch event handler or any of the action items, DispatchAction generates an AfterDispatch event. The AfterDispatch event does not occur if the BeforeDispatch event or any of the action items has already sent the response.

DispatchAction returns a Boolean value indicating whether the Web application should send the response message if it is not already sent. DispatchAction returns true if the action was handled by the action items and the AfterDispatch event handler did not change its Handled parameter to false.


TCustomWebDispatcher::DoAfterDispatch

TCustomWebDispatcher	See also

Generates an AfterDispatch event and returns a value that indicates whether the Web application can send the response.

bool __fastcall DoAfterDispatch(TWebRequest* Request, TWebResponse* Response);

Description

Applications cannot call DoAfterDispatch. The DispatchAction method calls DoAfterDispatch after sending the HTTP request message to any matching action items. The DispatchAction method does not call DoAfterDispatch if the HTTP request message was not handled by the action items or by a BeforeDispatch event handler. DoAfterDispatch is also not called if the message was already sent back to the Web client.

If the AfterDispatch event handler indicates that the response should not be sent, DoAfterDispatch returns false, and the Web application drops the connection without sending the response message. Otherwise, DoAfterDispatch returns true, and the Web application sends the response message if it was not sent from within the AfterDispatch event handler.


TCustomWebDispatcher::DoBeforeDispatch

TCustomWebDispatcher	See also

Generates a BeforeDispatch event and returns a value that indicates whether the dispatcher should look for action items to handle the request.

bool __fastcall DoBeforeDispatch(TWebRequest* Request, TWebResponse* Response);

Description

Applications cannot call DoBeforeDispatch. The DispatchAction method calls DoBeforeDispatch before trying to match the HTTP request message with any of its action items.

If the BeforeDispatch event handler indicates that it has handled the request message, DoBeforeDispatch returns true, and the DispatchAction method does not try to pass the request message to any of the action items. Otherwise, DoBeforeDispatch returns false, and unless the response message was sent from within the BeforeDispatch event handler, the DispatchAction method proceeds with looking for action items to handle the request message.

If DoBeforeDispatch returns true but the response has not been sent, DispatchAction generates an AfterDispatch event.


TCustomWebDispatcher::Notification

TCustomWebDispatcher	See also

Responds to notifications when objects are added to the module.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

Notification ensures that all TCustomContentProducer objects have access to the dispatcher, by setting their Dispatcher property as they are added to the application.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected

Published


Hierarchy

TObject

TPersistent

TComponent

TDataModule


TCustomContentProducer

Hierarchy	Properties	Methods	See also

TCustomContentProducer is the base class for all objects that produce the string that is sent as the contents of an HTTP response message.

Unit

httpapp

Description

Use TCustomContentProducer as a base class when defining a class to produce the contents of an HTTP response message. In most cases, the content producer will assemble a string of HTML commands. However, descendants of TCustomContentProducer can be defined to produce any valid MIME type.


TCustomContentProducer properties

TCustomContentProducer	Alphabetically	Legend

In TCustomContentProducer

Dispatcher

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomContentProducer properties

TCustomContentProducer	By object	Legend

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

DesignInfo

Dispatcher

Name

Owner

Tag

VCLComObject


TCustomContentProducer::Dispatcher

TCustomContentProducer	See also

Provides access to the dispatcher for the Web server application that includes the TCustomContentProducer object.

__property TCustomWebDispatcher* Dispatcher = {read=FDispatcher, write=SetDispatcher, stored=false};

Description

Use Dispatcher to get access to the dispatcher. The properties of the dispatcher give access to the TWebRequest and TWebResponse objects for the HTTP message that is currently being serviced. Use these objects to obtain detailed information about the message for which the content producer is generating a response string.


TCustomContentProducer methods

TCustomContentProducer	Alphabetically	Legend

In TCustomContentProducer

~TCustomContentProducer

Content

ContentFromStream

ContentFromString

Notification

TCustomContentProducer

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomContentProducer methods

TCustomContentProducer	By object	Legend

~TCustomContentProducer

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Content

ContentFromStream

ContentFromString

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Notification

RemoveComponent

SafeCallException

TCustomContentProducer


TCustomContentProducer::Content

TCustomContentProducer	See also

Returns the content produced by the content producer.

virtual System::AnsiString __fastcall Content(void);

Description

Call Content to retrieve the content for using in an HTTP response message. TCustomContentProducer returns an empty string. Descendants of TCustomContentProducer return the value of the content that they produce. In most cases, this content is a string of HTML commands, although it can be any valid MIME type.


TCustomContentProducer::ContentFromStream

TCustomContentProducer	See also

Returns the content produced in response to input read from a stream.

virtual System::AnsiString __fastcall ContentFromStream(Classes::TStream* Stream);

Description

Call ContentFromStream to retrieve the content produced by the content producer based on the information provided by the Stream parameter. TCustomContentProducer ignores the Stream parameter and returns the value created by the Content method.

Descendants of TCustomContentProducer override this method to interpret streamed input in their own way.


TCustomContentProducer::ContentFromString

TCustomContentProducer	See also

Returns the content produced in response to an input string.

virtual System::AnsiString __fastcall ContentFromString(const System::AnsiString S);

Description

Call ContentFromString to retrieve the content produced by the content producer based on the information provided by the S parameter. TCustomContentProducer ignores the string and returns the value created by the Content method.

Descendants of TCustomContentProducer override this method to interpret the input string in their own way.


TCustomContentProducer::Notification

TCustomContentProducer	See also

Overrides the inherited method to respond to messages that the dispatcher is going away.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the inherited method, Notification checks whether this call was triggered by the removal of the dispatcher. If so, the Dispatcher property is set to NULL.


TCustomContentProducer::TCustomContentProducer

TCustomContentProducer

Creates a new TCustomContentProducer object.

__fastcall virtual TCustomContentProducer(Classes::TComponent* AOwner) : Classes::TComponent(AOwner) { }

Description

Do not call the TCustomContentProducer constructor directly. Instead, use the new keyword, which returns an indirect reference to a newly instantiated TCustomContentProducer object.


TCustomContentProducer::~TCustomContentProducer

TCustomContentProducer

Frees the memory associated with the TCustomContentProducer object.

__fastcall virtual ~TCustomContentProducer(void) { }

Description

Do not call ~TCustomContentProducer directly. Instead, use the delete keyword on the object, which causes ~TCustomContentProducer to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TCustomActiveForm

Hierarchy	Properties	Methods	Events

TCustomActiveForm is the base class for ActiveForms.

Unit

forms

Description

TCustomActiveForm is used in code that is generated automatically by the ActiveForm wizard. For more information, see Generating an ActiveX control based on a VCL form.


TCustomActiveForm properties

TCustomActiveForm	Alphabetically	Legend

In TCustomActiveForm

AxBorderStyle

Derived from TCustomForm

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

BorderIcons

BorderStyle

Canvas

ClientHandle

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

FormStyle

HelpFile

Icon

KeyPreview

MDIChildCount

MDIChildren

Menu

ModalResult

ObjectMenuItem

OleFormObject

Parent

PixelsPerInch

Position

PrintScale

Scaled

TileMode

Visible

WindowMenu

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomActiveForm properties

TCustomActiveForm	By object	Legend

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

Align

AutoScroll

AxBorderStyle

BorderIcons

BorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHandle

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

FormStyle

Handle

Height

HelpContext

HelpFile

Hint

HorzScrollBar

Icon

KeyPreview

Left

MDIChildCount

MDIChildren

Menu

ModalResult

Name

ObjectMenuItem

OleFormObject

Owner

Parent

ParentFont

ParentWindow

PixelsPerInch

PopupMenu

Position

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

TileMode

Top

VCLComObject

VertScrollBar

Visible

Width

WindowMenu

WindowProc

WindowState


TCustomActiveForm::AxBorderStyle

TCustomActiveForm	See also

Sets the active form's border style.

enum TActiveFormBorderStyle { afbNone, afbSingle, afbSunken, afbRaised };

__property TActiveFormBorderStyle AxBorderStyle = {read=FAxBorderStyle, write=SetAxBorderStyle, default=1};

Description

AxBorderStyle takes one of the following values:

Values	Meaning

afbNone	No border appears around the active form.

afbSingle	A single line border appears around the active form.

afbSunken	The active form gets a sunken border.

afbRaised	The active form gets a raised border and no caption.


TCustomActiveForm events

TCustomActiveForm	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnClose

OnCloseQuery

OnCreate

OnDeactivate

OnDestroy

OnHelp

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TCustomActiveForm events

TCustomActiveForm	By object	Legend

OnActivate

OnClick

OnClose

OnCloseQuery

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHelp

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TCustomActiveForm methods

TCustomActiveForm	Alphabetically	Legend

In TCustomActiveForm

~TCustomActiveForm

CreateParams

TCustomActiveForm

WantChildKey

Derived from TCustomForm

Activate

ActiveChanged

ChangeScale

Close

CloseQuery

CreateWindowHandle

CreateWnd

Deactivate

DefaultHandler

DefineProperties

DefocusControl

DestroyWindowHandle

DoHide

DoShow

FocusControl

GetChildren

GetClientRect

GetFormImage

Hide

Loaded

Notification

Paint

PaintWindow

PaletteChanged

Print

ReadState

Release

Resize

SendCancelMode

SetChildOrder

SetFocus

SetFocusedControl

SetParent

Show

ShowModal

TCustomActiveForm

ValidateRename

VisibleChanging

WndProc

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomActiveForm methods

TCustomActiveForm	By object	Legend

~TCustomActiveForm

Activate

ActiveChanged

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ChangeScale

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

CreateParams

CreateWindowHandle

CreateWnd

Deactivate

DefaultHandler

DefineProperties

DefocusControl

DestroyComponents

Destroying

DestroyWindowHandle

DisableAlign

DisableAutoRange

Dispatch

DoHide

DoShow

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetChildren

GetClientRect

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

Loaded

MethodAddress

MethodName

NewInstance

Notification

Paint

PaintTo

PaintWindow

PaletteChanged

Perform

Print

ReadState

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

Resize

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetChildOrder

SetFocus

SetFocusedControl

SetParent

SetTextBuf

Show

ShowModal

TCustomActiveForm

Update

UpdateControlState

ValidateRename

VisibleChanging

WantChildKey

WndProc


TCustomActiveForm::TCustomActiveForm

See also

Creates a new TCustomActiveForm object.

__fastcall virtual TCustomActiveForm(Classes::TComponent* AOwner);

__fastcall TCustomActiveForm(Classes::TComponent* AOwner, int Dummy) : Forms::TCustomForm(AOwner, Dummy) { }

__fastcall TCustomActiveForm(HWND ParentWindow) : Forms::TCustomForm(ParentWindow) { }

Description

Do not create instances of TCustomActiveForm. TCustomActiveForm is intended only as a base class.

TCustomActiveForm performs the following tasks:

Sets the AxBorderStyle property to afbSingle.

Calls the parent object's constructor method.

Sets the BorderStyle property to bsNone.

Clears the BorderIcons property.

Sets the TabStop property to true.


TCustomActiveForm::TCustomActiveForm
TCustomActiveForm::CreateParams

See also

Updates the active form's creation parameters according to the value of the AxBorderStyle property.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams performs the following tasks:

Calls the inherited CreateParams method.

Removes the WS_CAPTION flag from Params::Style.

Adds flags to Params::Style and Params::ExStyle according to the value of the AxBorderStyle property, as shown in the following table:

If AxBorderStyle is	Then Style gets	And ExStyle gets

afbNone	Nothing	Nothing

afbSingle	WS_BORDER	Nothing

afbSunken	Nothing	WS_EX_CLIENTEDGE

afbRaised	WS_DLGFRAME	WS_EX_WINDOWEDGE

Note:	The creation parameters are not updated when the form is in design mode.


TCustomActiveForm::WantChildKey

See also

Overrides TCustomForm::WantChildKey in order to provide ActiveX functionality.

virtual bool __fastcall WantChildKey(Controls::TControl* Child, Messages::TMessage &Message);

Description

Do not call WantChildKey. It is used internally to ensure that keyboard events sent to child objects are handled correctly.


TCustomActiveForm::~TCustomActiveForm

TCustomActiveForm

~TCustomActiveForm frees the memory associated with the TCustomActiveForm object.

__fastcall virtual ~TCustomActiveForm(void) { }

Description

Do not call ~TCustomActiveForm directly. Instead, use the delete keyword on the object, which causes ~TCustomActiveForm to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm


TCustomCheckBox

Hierarchy	Properties	Methods	See also

TCustomCheckBox is the ancestor of all check-box components.

Unit

stdctrls

Description

TCustomCheckBox is an abstract class from which check-box components, including TCheckBox and TDBCheckBox, descend. Check boxes present the user with options that can be selected (checked) or deselected (unchecked).


TCustomCheckBox properties

TCustomCheckBox	Alphabetically	Legend

In TCustomCheckBox

Alignment

AllowGrayed

Checked

State

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomCheckBox properties

TCustomCheckBox	By object	Legend

Align

Alignment

AllowGrayed

BoundsRect

Brush

Checked

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

State

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomCheckBox::Alignment

TCustomCheckBox	Example

Controls the position of the check box’s caption.

__property Classes::TLeftRight Alignment = {read=FAlignment, write=SetAlignment, default=1};

Description

If Alignment is set to taRightJustify, the caption appears to the right of the check box. If Alignment is set to taLeftJustify, the caption appears to the left of the check box.


TCustomCheckBox::AllowGrayed

TCustomCheckBox	See also 	Example

Determines whether check box can be in a “grayed” state.

__property bool AllowGrayed = {read=FAllowGrayed, write=FAllowGrayed, default=0};

Description

If AllowGrayed is set to true, the check box has three possible states: checked, unchecked, and grayed. If AllowGrayed is set to false, the check box has only two possible states: checked and unchecked.


TCustomCheckBox::Checked

TCustomCheckBox	See also 	Example

Indicates whether the check box is selected.

__property bool Checked = {read=GetChecked, write=SetChecked, stored=false, nodefault};

Description

When Checked is true, a check mark appears in the check box (State = cbChecked), indicating that the option is selected. When Checked is false, the check box is either unchecked (State = cbUnchecked) or grayed (State = cbGrayed).


TCustomCheckBox::State

TCustomCheckBox	See also 	Example

Indicates whether the check box is selected, deselected, or grayed.

__property TCheckBoxState State = {read=FState, write=SetState, default=0};

Description

These are the possible values of State:

Value	Meaning

cbUnchecked	The check box has no check mark, indicating that the user has not selected the option.

cbChecked	The check box has a check mark in it, indicating that the user has selected the option.

cbGrayed	The check box has a check mark in it, but it is grayed.


TCustomCheckBox methods

TCustomCheckBox	Alphabetically	Legend

In TCustomCheckBox

~TCustomCheckBox

Click

CreateParams

CreateWindowHandle

CreateWnd

TCustomCheckBox

Toggle

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomCheckBox methods

TCustomCheckBox	By object	Legend

~TCustomCheckBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

ContainsControl

ControlAtPos

CreateParams

CreateWindowHandle

CreateWnd

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomCheckBox

Toggle

Update

UpdateControlState


TCustomCheckBox::Click

TCustomCheckBox 	See also

Click generates an OnClick event.

DYNAMIC void __fastcall Click(void);

Description

The protected Click method is called automatically when the check box is clicked with the mouse. In addition to generating an OnClick event, it sends a message to the parent control’s window to indicate that the state of the check box has changed.


TCustomCheckBox::TCustomCheckBox

TCustomCheckBox

Creates and initializes a TCustomCheckBox instance.

__fastcall virtual TCustomCheckBox(Classes::TComponent* AOwner);

__fastcall TCustomCheckBox(HWND ParentWindow) : Stdctrls::TButtonControl(ParentWindow) { }

Description

Do not instantiate a TCustomCheckBox object. To add a check box to a form, create an instance of a TCustomCheckBox descendant using the new keyword.

Pass a single component as a parameter to provide the check box with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the check box in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the check box is implemented as an ActiveX control.


TCustomCheckBox::TCustomCheckBox
TCustomCheckBox::CreateParams

TCustomCheckBox	See also

Initializes a window-creation parameter record.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams calls the inherited method, then makes specific adjustments for check boxes.


TCustomCheckBox::TCustomCheckBox
TCustomCheckBox::CreateWindowHandle

TCustomCheckBox	See also

Creates a window handle for the check box.

virtual void __fastcall CreateWindowHandle(const Controls::TCreateParams &Params);

Description

CreateWindowHandle implements special processing required by some Windows NT systems, then calls the inherited method.


TCustomCheckBox::TCustomCheckBox
TCustomCheckBox::CreateWnd

TCustomCheckBox	See also

Creates a Windows control corresponding to the check box.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd calls the inherited method, then sends a BM_SETCHECK message to set the check state of the control.


TCustomCheckBox::Toggle

TCustomCheckBox	See also

Changes the state of the check box.

virtual void __fastcall Toggle(void);

Description

Use the Toggle method to select or deselect the check box programmatically. Toggle switches among the valid check-box states—from checked to unchecked to grayed, or from checked to unchecked.


TCustomCheckBox::~TCustomCheckBox

TCustomCheckBox

~TCustomCheckBox frees the memory associated with the TCustomCheckBox object.

__fastcall virtual ~TCustomCheckBox(void) { }

Description

Do not call ~TCustomCheckBox directly. Instead, use the delete keyword on the object, which causes ~TCustomCheckBox to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TButtonControl


TCustomComboBox

Hierarchy	Properties	Methods	Events	See also

TCustomComboBox is the base class for combo-box components.

Unit

stdctrls

Description

Use TCustomComboBox as a base class when defining a control that represents a specialized Windows combo box. A combo box is an edit box with a scrollable list attached to it; users can select an item from the list or type directly into the edit box.

Do not create instances of TCustomComboBox. To put a combo box in a form, use a descendant of TCustomComboBox, such as TComboBox.


TCustomComboBox properties

TCustomComboBox	Alphabetically	Legend

In TCustomComboBox

Canvas

CharCase

DropDownCount

DroppedDown

EditHandle

ItemHeight

ItemIndex

Items

ListHandle

MaxLength

SelLength

SelStart

SelText

Sorted

Style

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomComboBox properties

TCustomComboBox	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

CharCase

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DropDownCount

DroppedDown

EditHandle

Enabled

Handle

Height

HelpContext

Hint

ItemHeight

ItemIndex

Items

Left

ListHandle

MaxLength

Name

Owner

Parent

ParentColor

ParentWindow

SelLength

SelStart

SelText

ShowHint

Showing

Sorted

Style

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomComboBox::Canvas

TCustomComboBox	See also

Provides access to the drawing surface for owner-draw combo boxes.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

Use Canvas as the drawing surface when implementing a handler for the OnDrawItem event.


TCustomComboBox::CharCase

TCustomComboBox	See also

Determines the case of the text in the combo box.

__property TEditCharCase CharCase = {read=FCharCase, write=SetCharCase, default=0};

Description

Use CharCase to force the contents of the combo box into upper or lower case. The possible values of CharCase are

Value	Meaning

ecLowerCase	The text is converted to lowercase.

ecNormal	The text appears in mixed case; it is not forced into any case. This is the default setting.

ecUpperCase	The text is converted to uppercase.

When CharCase is set to ecLowerCase or ecUpperCase, the case of characters is converted as the user types into the combo box. Changing the CharCase property changes the actual text, not just its appearance; case information is lost and cannot be recaptured by changing CharCase back to ecNormal.


TCustomComboBox::DropDownCount

TCustomComboBox	See also

Specifies the maximum number of items displayed in the drop-down list.

__property int DropDownCount = {read=FDropDownCount, write=FDropDownCount, default=8};

Description

By default, the drop-down list is long enough to contain eight items without requiring the user to scroll to see them all. To make the drop-down list smaller or larger, specify a number larger or smaller than eight as the DropDownCount value.

If the DropDownCount value is larger than the number of items in the Items property, the drop-down list will be just large enough to hold all the possible choices and no larger. If the DropDownCount value is smaller then the number of item in the Items property, the drop down list will display a scroll bar.

DropDownCount is meaningful only if Style is not csSimple.


TCustomComboBox::DroppedDown

TCustomComboBox	See also

Indicates whether the drop-down list is currently displayed.

__property bool DroppedDown = {read=GetDroppedDown, write=SetDroppedDown, nodefault};

Description

Read DroppedDown to determine whether the drop-down list is visible. Set DropDown to drop the list down or close it up. DroppedDown is true when the drop-down list is open, and false when it is closed.

DroppedDown is meaningful only if the value of Style is not csSimple.


TCustomComboBox::EditHandle

TCustomComboBox	See also

Provides access to the window handle for the edit portion of the combo box.

__property HWND EditHandle = {read=FEditHandle, nodefault};

Description

Read EditHandle for Windows API calls that need a handle for the window used by the edit portion of the combo box.


TCustomComboBox::ItemHeight

TCustomComboBox	See also

Specifies the height, in pixels, of the items in the drop-down list.

__property int ItemHeight = {read=GetItemHeight, write=SetItemHeight, nodefault};

Description

Use ItemHeight to specify the height needed to draw the items in the list when Style is set to csOwnerDrawFixed. If Style is csOwnerDrawVariable, ItemHeight is the default height for drawing list items. When Style is csOwnerDrawVariable, ItemHeight can be overridden by an OnMeasureItem event handler. If Style is set to any other value, the ItemHeight property is inoperative.


TCustomComboBox::ItemIndex

TCustomComboBox	See also	Example

Indicates which item in the drop-down list is selected.

__property int ItemIndex = {read=GetItemIndex, write=SetItemIndex, nodefault};

Description

Read ItemIndex to determine which item in the list is the value of the combo box. The first item in the list has index 0, the second item has index 1, and so on. If no item is selected, the value of ItemIndex is -1.

Set ItemIndex to programmatically select an item from the list.


TCustomComboBox::Items

TCustomComboBox	See also 	Example

Provides access to the list of items (strings) in the list portion of the combo box.

__property Classes::TStrings* Items = {read=FItems, write=SetItems};

Description

Use Items to access the list of items that appears in the combo box.


TCustomComboBox::ListHandle

TCustomComboBox	See also

Provides access to the window handle for the list portion of the combo box.

__property HWND ListHandle = {read=FListHandle, nodefault};

Description

Read ListHandle for Windows API calls that need a handle for the window used by the list portion of the combo box.


TCustomComboBox::MaxLength

TCustomComboBox	See also

Specifies the maximum number of characters the user can type into the edit portion of the combo box.

__property int MaxLength = {read=FMaxLength, write=SetMaxLength, default=0};

Description

Use MaxLength to limit the length of strings the user can type into the combo box. MaxLength does not affect the length of strings available in the list. If MaxLength is 0, there is no limit to the number of characters that can be entered.


TCustomComboBox::SelLength

TCustomComboBox	See also

Specifies the length, in characters, of the selected text in the edit portion of the combo box.

__property int SelLength = {read=GetSelLength, write=SetSelLength, nodefault};

Description

The selected portion of the text in the edit region of the combo box is the string of SelLength characters that starts at the character specified by the SelStart property. The selected text appears highlighted in the edit region of the combo box.

To select a section of text in the edit region, first set the SelStart property to position the cursor, and then set SelLength to the number of characters that should be selected. The SelText property is the substring that is selected.


TCustomComboBox::SelStart

TCustomComboBox	See also

Specifies the position of the first selected character in the edit box.

__property int SelStart = {read=GetSelStart, write=SetSelStart, nodefault};

Description

Read SelStart to determine where the selection starts in the Text property. The first character is designated with 0, the second with 1, and so on. When SelLength is 0, SelStart is the position of the cursor.

Set SelStart to position the cursor in the edit region of the combo box. Setting SelStart to 0 positions the cursor before the first character, setting SelStart to 1 positions the cursor before the second character, and so on.

Note:	Setting SelStart changes the SelLength property to 0. When using SelStart and SelLength to programmatically select a portion of the text in the edit region, set SelStart before setting SelLength.


TCustomComboBox::SelText

TCustomComboBox	See also

Represents the selected text in the edit region.

__property System::AnsiString SelText = {read=GetSelText, write=SetSelText};

Description

Read SelText to obtain the text that is selected in the edit region of the combo box. When the combo box is the active control, SelText appears highlighted. Set SelText to replace the current selection with a different substring. If no text is currently selected when a value is assigned to SelText, the SelText string is inserted in the text at the cursor.


TCustomComboBox::Sorted

TCustomComboBox	See also 	Example

Determines whether the list portion of the combo box is alphabetized.

__property bool Sorted = {read=FSorted, write=SetSorted, default=0};

Description

Set Sorted to true to sort the items in the Items list alphabetically. New items added to the list while Sorted is true are inserted in the correct alphabetical position.

When Sorted is changed from false to true, the original order of the items is lost. Setting Sorted back to false does not restore the original order.


TCustomComboBox::Style

TCustomComboBox	See also

Determines the display style of the combo box.

__property TComboBoxStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

Set Style to specify how the list and edit region of the combo box should appear. These are the possible values of the Style:

Value	Meaning

csDropDown	Creates a drop-down list with an edit box for manually entered text. All items are strings of the same height.

csSimple	Creates an edit box with a fixed list (list box) underneath. The length of the list is determined by the Height of the combo box.

csDropDownList	Creates a drop-down list with no edit box; the user cannot enter text manually. All items are strings of the same height.

csOwnerDrawFixed	Creates an owner-draw drop-down list with an edit box for manually entered text. Each item in the list is the height specified by the ItemHeight property.

csOwnerDrawVariable	Creates an owner-draw drop-down list with an edit box for manually entered text. List items can have varying heights.

When Style is csOwnerDrawFixed or csOwnerDrawVariable, the OnDrawItem event occurs when the list items need to be drawn. If Style is csOwnerDrawVariable, an OnMeasureItem event occurs as well.


TCustomComboBox events

TCustomComboBox	Alphabetically	Legend

In TCustomComboBox

OnChange

OnDrawItem

OnDropDown

OnMeasureItem


TCustomComboBox events

TCustomComboBox	By object	Legend

OnChange

OnDrawItem

OnDropDown

OnMeasureItem


TCustomComboBox::OnChange

TCustomComboBox	See also 	Example

Occurs when the text displayed in the edit region changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action immediately after the user edits the text in the edit region or selects an item from the list. The Text property gives the new value in the edit region.


TCustomComboBox::OnDrawItem

TCustomComboBox	See also

Occurs when an item in an owner-draw combo box needs to be displayed.

enum StdCtrls__9 { odSelected, odGrayed, odDisabled, odChecked, odFocused };

typedef Set<StdCtrls__9, odSelected, odFocused>  TOwnerDrawState;

typedef void __fastcall (__closure *TDrawItemEvent)(Controls::TWinControl* Control, int Index, const Windows::TRect &Rect, TOwnerDrawState State);

__property TDrawItemEvent OnDrawItem = {read=FOnDrawItem, write=FOnDrawItem};

Description

Write an OnDrawItem event handler to draw the items in the drop-down list of an owner-draw combo box. An OnDrawItem event handler can add graphic elements to the list items, or replace the list item text by graphics. OnDrawItem passes four parameters to its event handler:

•	Control: A reference to the combo box containing the item.

•	Index: The index of the item in the Items property.

•	&Rect: A rectangle in which to draw.

•	State: The state of the item, which can take one of the following values:

Value	Meaning

odSelected	The item is selected.

odGrayed	The item is grayed.

odDisabled	The item is disabled.

odChecked	The item is checked.

odFocused	The item currently has input focus.

Draw the items on the Canvas using the coordinates provided by the Rect parameter. OnDrawItem occurs only if Style is set to csOwnerDrawFixed or csOwnerDrawVariable.

If an OnDrawItem event handler is not provided, the combo box fills the Rect parameter with the current brush and writes the text value of the item specified by the Index parameter.


TCustomComboBox::OnDropDown

TCustomComboBox	See also 	Example

Occurs when the user opens the drop-down list by clicking the arrow at the right of the control.

__property Classes::TNotifyEvent OnDropDown = {read=FOnDropDown, write=FOnDropDown};

Description

Write an OnDropDown event handler to implement special processing that needs to occur only when the drop-down list is activated.


TCustomComboBox::OnMeasureItem

TCustomComboBox 	See also

Occurs when an item in a csOwnerDrawVariable combo box needs to be redisplayed.

typedef void __fastcall (__closure *TMeasureItemEvent)(Controls::TWinControl* Control, int Index, int &Height);

__property TMeasureItemEvent OnMeasureItem = {read=FOnMeasureItem, write=FOnMeasureItem};

Description

When Style is set to csOwnerDrawVariable, the OnMeasureItem event precedes OnDrawItem. Write an OnMeasureItem event handler to specify the height, in pixels, needed to draw an item in the drop-down list.

OnMeasureItem passes three parameters to its event handler:

•	Control: A reference to the combo box containing the item.

•	Index: The index of the item in the Items property.

•	&Height: The default height of the item, in pixels.

The event handler can reset the final parameter, Height, to the appropriate value.


TCustomComboBox methods

TCustomComboBox	Alphabetically	Legend

In TCustomComboBox

~TCustomComboBox

Change

Clear

ComboWndProc

CreateParams

CreateWnd

DestroyWnd

DrawItem

DropDown

MeasureItem

SelectAll

SetStyle

TCustomComboBox

WndProc

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomComboBox methods

TCustomComboBox	By object	Legend

~TCustomComboBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ComboWndProc

ContainsControl

ControlAtPos

CreateParams

CreateWnd

DefaultHandler

DestroyComponents

Destroying

DestroyWnd

DisableAlign

Dispatch

DragDrop

Dragging

DrawItem

DropDown

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MeasureItem

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetStyle

SetTextBuf

Show

TCustomComboBox

Update

UpdateControlState

WndProc


TCustomComboBox::Change

TCustomComboBox	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(void);

Description

Change is the protected implementation method for the OnChange event. Override this method to add additional processing when the text changes, or to block the OnChange event.

When overriding Change, call the inherited Change or Changed method.


TCustomComboBox::Clear

TCustomComboBox	See also

Deletes all text from the edit box and all items from the Items list.

void __fastcall Clear(void);

Description

Call Clear to empty the combo box at runtime.


TCustomComboBox::ComboWndProc

TCustomComboBox	See also

Provides message responses for the combo box.

virtual void __fastcall ComboWndProc(Messages::TMessage &Message, HWND ComboWnd, void * ComboProc);

Description

ComboWndProc is the first procedure to receive Windows messages that are sent to the window of the edit region or list portion of the combo box. The Message parameter describes the windows message. The ComboWnd parameter is the windows handle for the edit region or list. The ComboProc parameter is a pointer to the default window procedure for the window that received the message. ComboWndProc provides default responses to focus events, mouse events, and key strokes.

Override ComboWndProc to change the way the combo box responds to Windows messages. When overriding ComboWndProc, be sure to call the inherited method to process all unhandled messages.


TCustomComboBox::TCustomComboBox

TCustomComboBox	See also

Creates and initializes a TCustomComboBox instance.

__fastcall TCustomComboBox(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

__fastcall virtual TCustomComboBox(Classes::TComponent* AOwner);

Description

Do not instantiate a TCustomComboBox object. To add a combo box to a form, create an instance of a TCustomComboBox descendant using the new keyword.

Pass a single component as a parameter to provide the combo box with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the combo box in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the combo box is implemented as an ActiveX control.


TCustomComboBox::TCustomComboBox
TCustomComboBox::CreateParams

TCustomComboBox	See also

Initializes the window-creation parameter record.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it uses to create the window for the combo box. CreateParams overrides the inherited method to implement the Style property.


TCustomComboBox::TCustomComboBox
TCustomComboBox::CreateWnd

TCustomComboBox	See also

Creates the Windows control that represents the combo box.

virtual void __fastcall CreateWnd(void);

Description

The Windows control for the combo box can be temporarily destroyed and recreated in order to set properties that require changing the window creation parameters. TCustomComboBox calls CreateWnd to create this Windows control when necessary.


TCustomComboBox::~TCustomComboBox

TCustomComboBox	See also

Destroys the combo box and frees its memory.

__fastcall virtual ~TCustomComboBox(void);

Description

Do not call ~TCustomComboBox directly. Instead, use the delete keyword on the object, which causes ~TCustomComboBox to be invoked automatically.


TCustomComboBox::~TCustomComboBox
TCustomComboBox::DestroyWnd

TCustomComboBox	See also

Destroys the Windows control that represents the combo box.

virtual void __fastcall DestroyWnd(void);

Description

The Windows control for the combo box can be temporarily destroyed and recreated in order to set properties that require changing the window creation parameters. TCustomComboBox calls DestroyWnd to destroy this Windows control when necessary.

DestroyWnd saves the contents of Items list before calling the inherited DestroyWnd method. The saved list is used if the window is recreated.


TCustomComboBox::DrawItem

TCustomComboBox	See also

Generates an OnDrawItem event.

virtual void __fastcall DrawItem(int Index, const Windows::TRect &Rect, TOwnerDrawState State);

Description

When Style is csOwnerDrawFixed or csOwnerDrawVariable, DrawItem is called whenever an item in the list needs to be drawn. If an OnDrawItem event handler is assigned, DrawItem generates an OnDrawItem event, passing the Index, Rect, and State parameters to the event handler. Otherwise, OnDrawItem fills the rectangle passed in Rect and draws any text associated with the indexed item, ignoring the State parameter.

Override DrawItem to provide class-specific drawing code for the items in the list.


TCustomComboBox::DropDown

TCustomComboBox	See also

Generates an OnDropDown event.

DYNAMIC void __fastcall DropDown(void);

Description

DropDown is the protected implementation method for the OnDropDown event. To perform additional processing or block the OnDropDown event, override DropDown.


TCustomComboBox::MeasureItem

TCustomComboBox	See also

Generates an OnMeasureItem event.

virtual void __fastcall MeasureItem(int Index, int &Height);

Description

MeasureItem is the protected implementation method for the OnMeasureItem event. Override MeasureItem to provide class-specific code to specify the size of list items when Style is csOwnerDrawVariable.


TCustomComboBox::SelectAll

TCustomComboBox	See also

Selects the entire block of text in the edit box.

void __fastcall SelectAll(void);

Description

Use SelectAll to select all the text in the edit box. To select only part of the text, use the SelStart and SelLength properties.


TCustomComboBox::SetStyle

TCustomComboBox	See also

Sets the Style property.

virtual void __fastcall SetStyle(TComboBoxStyle Value);

Description

SetStyle is the protected implementation method for the Style property. Override SetStyle to change the implementation of the Style property.


TCustomComboBox::WndProc

TCustomComboBox	See also

Processes messages received by the combo box.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc is the first method to received Windows messages that are sent to the combo box. Messages sent to the child windows of the combo box (for the edit region and the list portion) go to the ComboWndProc method instead. WndProc handles messages about changes to the system colors defined in the Windows control panel, and closes up the drop-down list when the Enter key or the Escape key is pressed. All other messages are passed to Dispatch for default processing.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomControl

Hierarchy	Properties	Methods	See also

TCustomControl is the abstract base class from which to derive windowed controls that require the support of a Canvas for drawing complex visual images.

Unit

controls

Description

Standard windowed controls already “know” how to display themselves, because they are part of Windows. Thus, a button or a check box component descends directly from TWinControl. When creating original windowed controls that do not correspond to standard Windows components, derive them from TCustomControl, rather than directly from TWinControl. TCustomControl makes drawing original controls easier by providing a Canvas property to manage the drawing surface and a virtual Paint method that is called to respond to WM_PAINT messages.

When creating custom controls that don’t need to receive input focus, derive them from TGraphicControl instead of TCustomControl, to avoid the overhead associated with being a windowed control. Painting a windowed control is slower than painting a graphic control.


TCustomControl properties

TCustomControl	Alphabetically	Legend

In TCustomControl

Canvas

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomControl properties

TCustomControl	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomControl::Canvas

TCustomControl	See also 	Example

Specifies the TCanvas object that presents a drawing surface for the control.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

Use the properties of the TCanvas object to draw or paint on the surface of the control. Canvas encapsulates a Windows device context, providing all the tools and methods needed for drawing and painting.

Canvas is a protected property that is usually redeclared as public in descendants of TCustomControl.


TCustomControl methods

TCustomControl	Alphabetically	Legend

In TCustomControl

~TCustomControl

Paint

PaintWindow

TCustomControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomControl methods

TCustomControl	By object	Legend

~TCustomControl

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Paint

PaintTo

PaintWindow

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomControl

Update

UpdateControlState


TCustomControl::TCustomControl

TCustomControl	See also

Creates an instance of TCustomControl.

__fastcall virtual TCustomControl(Classes::TComponent* AOwner);

__fastcall TCustomControl(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not call TCustomControl directly. Instead, use the new keyword to obtain an indirect reference to a newly instantiated custom control. Objects placed on forms at design time are created automatically, and do not need to be explicitly created.

TCustomControl creates the canvas for the custom control after calling the parent object's constructor. Pass a single Component as a parameter to provide the custom control with an Owner that is responsible for freeing the custom control. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the custom control in a non-VCL window. This syntax is used when the custom control is implemented as an ActiveX control that is embedded in a non-VCL window.


TCustomControl::~TCustomControl

TCustomControl	See also

Destroys an instance of TCustomControl.

__fastcall virtual ~TCustomControl(void);

Description

Do not call ~TCustomControl directly in an application. Instead, use the delete keyword, that takes an indirect reference to the custom control.


TCustomControl::Paint

TCustomControl	See also

Renders the image of a custom control.

virtual void __fastcall Paint(void);

Description

The Paint method for TCustomControl does nothing other than provide an interface for a method that responds to WM_PAINT messages. Paint is called by the PaintWindow method, after that method has supplied the Canvas with the handle to a device context. When creating a custom control, always override Paint to draw the image of the control.


TCustomControl::PaintWindow

TCustomControl	See also

Renders the image of the control on a specified device context.

virtual void __fastcall PaintWindow(HDC DC);

Description

PaintWindow is called automatically when a custom control receives a WM_PAINT message. PaintWindow provides a Windows device context for the canvas, calls the Paint method, and finally removes the device context. Override PaintWindow to provide additional responses to the WM_PAINT message. To draw the image of the control, override the Paint method instead.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomDBGrid

Hierarchy	Properties	Methods	Events	See also

TCustomDBGrid is the abstract base class for grid controls that display the records from a dataset in a tabular format.

Unit

dbgrids

Description

TCustomDBGrid introduces new properties, events, and methods to expand the capabilities of TCustomGrid for displaying the fields from a dataset. At runtime, users can manipulate TCustomDBGrid objects using the TDBNavigator object.

Do not create instances of TCustomDBGrid. Use TCustomDBGrid as a base class when declaring grid objects that display information from datasets. Properties and methods of TCustomDBGrid provide basic behavior that descendent classes inherit as well as behavior that components can override to customize their behavior.


TCustomDBGrid properties

TCustomDBGrid	Alphabetically	Legend

In TCustomDBGrid

Columns

DataLink

DataSource

DefaultDrawing

FieldCount

Fields

IndicatorOffset

LayoutLock

Options

ReadOnly

SelectedField

SelectedIndex

SelectedRows

TitleFont

UpdateLock

Derived from TCustomGrid

EditorMode

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomDBGrid properties

TCustomDBGrid	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DataLink

DataSource

DefaultDrawing

DesignInfo

EditorMode

Enabled

FieldCount

Fields

Handle

Height

HelpContext

Hint

IndicatorOffset

LayoutLock

Left

Name

Options

Owner

Parent

ParentColor

ParentWindow

ReadOnly

SelectedField

SelectedIndex

SelectedRows

ShowHint

Showing

TabOrder

TabStop

Tag

TitleFont

Top

UpdateLock

VCLComObject

Visible

Width

WindowProc


TCustomDBGrid::Columns

TCustomDBGrid	See also

Describes the display attributes and field bindings of the columns.

__property TDBGridColumns* Columns = {read=FColumns, write=SetColumns};

Description

Use Columns to read or set the field bindings and display attributes of the columns in the data-aware grid. Columns is an indexed collection of TColumn objects. Use the properties of the TColumn objects to specify the display attributes or field bindings of individual columns in the grid. The field binding of a column designates a field within the dataset specified by the DataSource property.

Columns can be set at design time through the Columns editor, or programmatically at runtime.


TCustomDBGrid::DataLink

TCustomDBGrid	See also

Helps the data-aware grid manage its link to the data source and respond to data events.

__property TGridDataLink* DataLink = {read=FDataLink};

Description

Applications should not need to use the DataLink property. It is exposed as a protected property so that component writers can use descendants of TGridDataLink to respond to additional data events.

DataLink helps TCustomDBGrid to

•	Resolve the field bindings specified by Columns with the fields in the dataset.

•	Respond to changes in the values of fields.

•	Respond to changes in record currency.

•	Respond to changes in the editing state of the dataset.

•	Keep track of unposted edits and discard or post them as appropriate.


TCustomDBGrid::DataSource

TCustomDBGrid	See also

Identifies the link to the dataset where the data-aware grid finds its data.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Set DataSource to the TDataSource object that links to the dataset where the data-aware grid should fetch its data. DataSource allows the data-aware grid to read from, write to, and navigate around the dataset.


TCustomDBGrid::DefaultDrawing

TCustomDBGrid	See also

Indicates whether the cells in the data-aware grid are drawn automatically.

__property bool DefaultDrawing = {read=FDefaultDrawing, write=FDefaultDrawing, default=1};

Description

Set DefaultDrawing to true to allow the data-aware grid to draw the data in the cells of the grid automatically. Set DefaultDrawing to false to turn off the default drawing when providing customized painting in an OnDrawColumnCell event handler or an OnDrawDataCell event handler.

When DefaultDrawing is true, the data-aware grid fetches the data for each cell from the appropriate entry in the Fields array, and writes it to the cell. It then draws the focus rectangle if the cell has focus, or if the cell is selected and the Options property includes dgAlwaysShowSelection.

When DefaultDrawing is false, the data-aware grid draws the appropriate background color on the cell and sets up the brush and font described by the appropriate TColumn object. However, the value of the field is not written to the cell, and no focus rectangle is drawn.


TCustomDBGrid::FieldCount

TCustomDBGrid	See also

Specifies the number of fields (columns) displayed in the grid.

__property int FieldCount = {read=GetFieldCount, nodefault};

Description

Use FieldCount to iterate through all the field components indexed by the Fields property. FieldCount may differ from the number of fields in the underlying dataset because the grid may contain calculated fields, and not all fields in the dataset are necessarily shown in the grid. Individual fields are removed and calculated fields are added using the Columns editor at design time.

FieldCount is the same as the number of columns at runtime. At design time, the grid may contain empty columns.


TCustomDBGrid::Fields

TCustomDBGrid	See also

Provides indexed access to the field components that correspond to the columns.

__property Db::TField* Fields[int FieldIndex] = {read=GetFields};

Description

Use Fields to gain direct access to the field component in the dataset for a particular column in the grid. The field for the first data column is obtained using an Index of 0, the field for the second data column using an Index of 1, and so on. The range for Index is 0... FieldCount - 1.

The first data column in the grid may not be the same as the first column in the grid. If Options includes dgIndicator, the first column in the grid will be a non-scrolling columns that contains the current row indicator.

The individual field components in Fields can be used to obtain information such as the value of the field on the current record, its preferred display width, or the string to draw when displaying or editing the field. Use the field component to write values directly to the dataset without using the editor in the cell.

Note:	If the column in the grid represents a calculated field, there is no field component for that column in the dataset. Fields returns NULL when the Index specifies the column that contains a calculated field. To obtain the field component for a calculated field, use the GetColField method.


TCustomDBGrid::IndicatorOffset

TCustomDBGrid	See also

Indicates the index of the first column in the grid that contains data.

__property Byte IndicatorOffset = {read=FIndicatorOffset, nodefault};

Description

Use IndicatorOffset to convert between the positions of the columns in the Columns property and the columns drawn on the data-aware grid. IndicatorOffset is 1 if the Options property includes dgIndicator, because the first column of the grid is used for the current row indicator. IndicatorOffset is 0 if all columns contain data.


TCustomDBGrid::LayoutLock

TCustomDBGrid	See also

Counts the number of times BeginLayout has been called without an EndLayout or CancelLayout call.

__property Byte LayoutLock = {read=FLayoutLock, nodefault};

Description

Use LayoutLock to determine when the column bindings change. Whenever a column width or binding changes or the fields in the data source change, the BeginLayout method is called. BeginLayout increments LayoutLock to keep track of the fact that the column bindings are changing. When changes are complete, the EndLayout method is called. EndLayout decrements LayoutLock. When LayoutLock returns to 0, the data-aware grid knows that all changes are complete, and the Fields and Columns properties are updated.


TCustomDBGrid::Options

TCustomDBGrid 	See also

Specifies various display and behavioral properties of the data-aware grid.

enum TDBGridOption { dgEditing, dgAlwaysShowEditor, dgTitles, dgIndicator, dgColumnResize, dgColLines, dgRowLines, dgTabs, dgRowSelect, dgAlwaysShowSelection, dgConfirmDelete, dgCancelOnExit, dgMultiSelect };

typedef Set<TDBGridOption, dgEditing, dgMultiSelect>  TDBGridOptions;

__property TDBGridOptions Options = {read=FOptions, write=SetOptions, default=3325};

Description

Set Options to include the desired properties for the data-aware grid. Options is a set drawn from the following values:

Value	Meaning

dgEditing	The user can edit data using the grid. dgEditing is ignored if Options includes dgRowSelect.

dgAlwaysShowEditor	 The grid is always in edit mode. That is, the user does not have to press Enter or F2 before editing the contents of a cell. dgAlwaysShowEditor does nothing unless dgEditing is also included in Options. dgAlwaysShowEditor is ignored if Options includes dgRowSelect.

dgTitles	Titles appear at the top of the columns in the grid.

dgIndicator	A small pointer appears in the first column to indicate which row is current.

dgColumnResize	Columns that are bound to fields can be resized or moved.

dgColLins	Lines appear between columns in the grid.

dgRowLines	Lines appear between the rows of the grid.

dgTabs	The user can navigate through the grid using the Tab and Shift+Tab keys.

dgRowSelect	The user can select an entire row, as well as selecting individual cells. If Options includes dgRowSelect, dgEditing and dgAlwaysShowEditor are ignored.

dgAlwaysShowSelection	The selected cell displays the focus rectangle even when the grid does not have focus.

dgConfirmDelete	A message box appears, asking for confirmation, when the user types Ctrl+Delete to delete a row in the grid.

dgCancelOnExit	When the user exits the grid from an inserted record to which the user made no modifications, the inserted record is not posted to the dataset. This prevents the inadvertent posting of empty records.

dgMultiSelect	More than one row in the grid can be selected at a time.


TCustomDBGrid::ReadOnly

TCustomDBGrid	See also

Indicates whether the grid is used for display only, or whether the user can edit data using the grid.

__property bool ReadOnly = {read=FReadOnly, write=FReadOnly, default=0};

Description

Set ReadOnly to true to prevent users from changing the data in the dataset. Set ReadOnly to false to allow users to edit data using the grid.

When ReadOnly is true, users cannot use the Insert key to insert a new row in the grid or use the Down Arrow key to add a row to the end of the grid.


TCustomDBGrid::SelectedField

TCustomDBGrid	See also 	Example

Specifies the field component for the currently selected cell in the grid.

__property Db::TField* SelectedField = {read=GetSelectedField, write=SetSelectedField};

Description

Set SelectedField to move focus to a particular field in the grid. Read SelectedField to obtain access to the field component for the currently selected cell. If there is not currently selected cell, SelectedField is NULL. For example, when an entire row is selected, SelectedField is NULL.


TCustomDBGrid::SelectedIndex

TCustomDBGrid	See also

Specifies the index of the currently selected column in the Columns array.

__property int SelectedIndex = {read=GetSelectedIndex, write=SetSelectedIndex, nodefault};

Description

Set SelectedIndex to move focus to a column in the grid that is identified by position. Read SelectedIndex to determine which column in the grid has focus. A value of 0 indicates the first data column, 1 is the second data column, and so on. SelectedIndex is -1 if there is no currently selected column.

If the Options property includes dgIndicator, the index of the data column given by SelectedIndex will differ from the index of the physical column in the grid.

To access the field component for the selected column, use the SelectedField property.


TCustomDBGrid::SelectedRows

TCustomDBGrid	See also

Specifies a set of bookmarks for all the records in the dataset that correspond to rows selected in the grid.

__property TBookmarkList* SelectedRows = {read=FBookmarks};

Description

Use the properties and methods of the TBookmarkList object returned by SelectedRows to

•	Determine the number of rows in the grid that are selected.

•	Determine whether the current record in the dataset is selected.

•	Determine whether a particular record in the dataset is selected.

•	Delete all selected rows from the dataset.

SelectedRows is only meaningful when the Options property includes dgRowSelect. SelectedRows can only identify a single row unless the Options property includes dgMultiSelect.


TCustomDBGrid::TitleFont

TCustomDBGrid	See also

Describes the font used to draw the column titles in the grid.

__property Graphics::TFont* TitleFont = {read=FTitleFont, write=SetTitleFont};

Description

Set TitleFont to change the font used to draw the column headings. TitleFont is only meaningful if the Options property includes dgTitles.


TCustomDBGrid::UpdateLock

TCustomDBGrid	See also

Counts the number of times BeginUpdate is called without a corresponding call to EndUpdate.

__property Byte UpdateLock = {read=FUpdateLock, nodefault};

Description

UpdateLock prevents the grid from repainting while the data in the grid changes. Whenever a change is made that affects the data that is drawn in the grid, the BeginUpdate method is called. BeginUpdate increments UpdateLock to keep track of the fact that the contents of the grid are changing. When changes are complete, the EndUpdate method is called. EndUpdate decrements UpdateLock.

When UpdateLock returns to 0, the data-aware grid can repaint its cells. When UpdateLock is greater than 0, the grid defers repaints. UpdateLock prevents the grid from flickering when the grid is resized or the user scrolls through the data.


TCustomDBGrid events

TCustomDBGrid	Alphabetically	Legend

In TCustomDBGrid

OnCellClick

OnColEnter

OnColExit

OnColumnMoved

OnDrawColumnCell

OnDrawDataCell

OnEditButtonClick

OnTitleClick


TCustomDBGrid events

TCustomDBGrid	By object	Legend

OnCellClick

OnColEnter

OnColExit

OnColumnMoved

OnDrawColumnCell

OnDrawDataCell

OnEditButtonClick

OnTitleClick


TCustomDBGrid::OnCellClick

TCustomDBGrid	See also

Occurs when the user releases the mouse in one of the cells of the grid.

typedef void __fastcall (__closure *TDBGridClickEvent)(TColumn* Column);

__property TDBGridClickEvent OnCellClick = {read=FOnCellClick, write=FOnCellClick};

Description

Write an OnCellClick event handler to take specific action when the user clicks in one of the cells of the data-aware grid. The Column parameter is the TColumn object that corresponds to the column where the mouse was when the user released the left mouse button.

OnCellClick occurs when the user releases the mouse. To take action when the user clicks down on the mouse, use the OnColEnter event.

OnCellClick will not occur when the mouse is released at the end of resizing a row or column, or when the cell is being edited.


TCustomDBGrid::OnColEnter

TCustomDBGrid	See also 	Example

Occurs when focus moves to a new cell in the grid.

__property Classes::TNotifyEvent OnColEnter = {read=FOnColEnter, write=FOnColEnter};

Description

Write an OnColEnter event handler to take specific action when a new cell has just been selected. Focus moves to a cell when

•	The user navigates to the cell using the keyboard. For example, when the user uses the Tab key, or the Home key.

•	The user clicks the mouse button down in the cell.

•	The SelectedField or SelectedIndex property is set.

Read the SelectedField or SelectedIndex property to determine which cell was just entered.


TCustomDBGrid::OnColExit

TCustomDBGrid	See also 	Example

Occurs just before a cell in the grid loses input focus.

__property Classes::TNotifyEvent OnColExit = {read=FOnColExit, write=FOnColExit};

Description

Write an OnColExit event handler to take specific action when a cell is about to lose focus. For example, use OnColExit to post edits to the underlying dataset when the user leaves a cell, rather than waiting for the user to leave the record.

A cell loses focus when

•	The user navigates out of the cell using the keyboard. For example, when the user presses the Tab key or the Home key.

•	The user clicks the mouse button down in another cell.

•	The SelectedField or SelectedIndex property is set.

When the selected cell in the data-aware grid changes, first the OnColExit event occurs. Then the values of SelectedField and SelectedIndex are updated. Finally the OnColEnter event occurs. Thus, in an OnColExit event handler, the SelectedField or SelectedIndex property can be used to determine which column is about to lose focus.


TCustomDBGrid::OnColumnMoved

TCustomDBGrid	See also

Occurs when the user moves a column using the mouse.

typedef void __fastcall (__closure *TMovedEvent)(System::TObject* Sender, int FromIndex, int ToIndex);

__property Grids::TMovedEvent OnColumnMoved = {read=FOnColumnMoved, write=FOnColumnMoved};

Description

Write an OnColumnMoved event handler to take specific action just after a column in the grid has been moved. The FromIndex parameter gives the position the column previously occupied in the Columns array. The ToIndex parameter gives the position the column now occupies.

OnColumnMoved can only occur when the Options property includes dgColumnResize.


TCustomDBGrid::OnDrawColumnCell

TCustomDBGrid	See also

Occurs when the grid needs to paint a cell.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

typedef void __fastcall (__closure *TDrawColumnCellEvent)(System::TObject* Sender, const Windows::TRect &Rect, int DataCol, TColumn* Column, Grids::TGridDrawState State);

__property TDrawColumnCellEvent OnDrawColumnCell = {read=FOnDrawColumnCell, write=FOnDrawColumnCell};

Description

Write an OnDrawColumnCell event handler to provide customized drawing for the data in the cells of the grid. Draw on the cell using the methods of the Canvas property. The Rect parameter indicates the location of the cell on the canvas. The DataCol parameter is the index of the column in the Columns array. The Column parameter is the TColumn object that describes the display attributes and field binding for the cell. The State parameter indicates whether the cell has input focus, whether the cell is selected, and whether the cell is a fixed (non-data) cell such as a column header.

An OnDrawColumnCell event handler can call the DefaultDrawColumnCell method to instruct the data-aware grid to write the data value in the cell. The OnDrawColumnCell event handler can augment the DefaultDrawColumnCell method to provide visual indications of selection and focus. If the OnDrawColumnCell event handler does not use DefaultDrawColumnCell to draw the text for the cell, use the GetFieldValue method to get the text that should be displayed in the cell.

If DefaultDrawing is true, the data will already be drawn in the cell before the OnDrawColumnCell event, and the grid draws a focus rectangle around selected cells after the OnDrawColumnCell event.

Note:	If the Columns property has a State property of csDefault, the OnDrawDataCell event occurs before the OnDrawColumnCell. The OnDrawDataCell event is obsolete, and only included for backward compatibility. Do not set both an OnDrawDataCell event handler and an OnDrawColumnCell event handler.


TCustomDBGrid::OnDrawDataCell

TCustomDBGrid	See also

Occurs when the grid needs to paint a cell if the State property of Columns is csDefault.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

typedef void __fastcall (__closure *TDrawDataCellEvent)(System::TObject* Sender, const Windows::TRect &Rect, Db::TField* Field, Grids::TGridDrawState State);

__property TDrawDataCellEvent OnDrawDataCell = {read=FOnDrawDataCell, write=FOnDrawDataCell};

Description

Do not write an OnDrawDataCell event handler. OnDrawDataCell is obsolete and included for backward compatibility. Instead, write an OnDrawColumnCell event handler.


TCustomDBGrid::OnEditButtonClick

TCustomDBGrid	See also

Occurs when the user presses the ellipsis button in a grid column.

__property Classes::TNotifyEvent OnEditButtonClick = {read=FOnEditButtonClick, write=FOnEditButtonClick };

Description

Write an OnEditButtonClick event handler to bring up an appropriate list or dialog when the user presses the ellipsis button in a grid cell. The OnEditButtonClick event handler can set the value of the field based on the user response to the list or dialog. Use the SelectedField property to access the TField component whose value should be set.


TCustomDBGrid::OnTitleClick

TCustomDBGrid	See also

Occurs when the user releases the mouse in one of the column headers.

typedef void __fastcall (__closure *TDBGridClickEvent)(TColumn* Column);

__property TDBGridClickEvent OnTitleClick = {read=FOnTitleClick, write=FOnTitleClick};

Description

Write an OnTitleClick event handler to take specific action when the user clicks in one of the column headers. The Column parameter is the TColumn object that corresponds to the column where the mouse was when the user released the left mouse button.


TCustomDBGrid methods

TCustomDBGrid	Alphabetically	Legend

In TCustomDBGrid

~TCustomDBGrid

AcquireLayoutLock

BeginLayout

BeginUpdate

CancelLayout

CanEditAcceptKey

CanEditModify

CanEditShow

CellClick

ColEnter

ColExit

ColumnMoved

ColWidthsChanged

CreateColumns

CreateEditor

CreateWnd

DataToRawColumn

DefaultDrawColumnCell

DefaultDrawDataCell

DefaultHandler

DeferLayout

DefineFieldMap

DefineProperties

DrawCell

DrawColumnCell

DrawDataCell

EditButtonClick

EndLayout

EndUpdate

GetColField

GetEditLimit

GetEditMask

GetEditText

GetFieldValue

HighlightCell

KeyDown

KeyPress

LayoutChanged

LinkActive

Loaded

MouseDown

MouseUp

Notification

RawToDataColumn

Scroll

SetColumnAttributes

SetEditText

StoreColumns

TCustomDBGrid

TimedScroll

TitleClick

ValidFieldIndex

Derived from TCustomGrid

MouseCoord

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomDBGrid methods

TCustomDBGrid	By object	Legend

~TCustomDBGrid

AcquireLayoutLock

Assign

BeginDrag

BeginLayout

BeginUpdate

BringToFront

Broadcast

CancelLayout

CanEditAcceptKey

CanEditModify

CanEditShow

CanFocus

CellClick

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ColEnter

ColExit

ColumnMoved

ColWidthsChanged

ContainsControl

ControlAtPos

CreateColumns

CreateEditor

CreateWnd

DataToRawColumn

DefaultDrawColumnCell

DefaultDrawDataCell

DefaultHandler

DeferLayout

DefineFieldMap

DefineProperties

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

DrawCell

DrawColumnCell

DrawDataCell

EditButtonClick

EnableAlign

EndDrag

EndLayout

EndUpdate

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetColField

GetEditLimit

GetEditMask

GetEditText

GetFieldValue

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

HighlightCell

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

KeyPress

LayoutChanged

LinkActive

Loaded

MethodAddress

MethodName

MouseCoord

MouseDown

MouseUp

NewInstance

Notification

PaintTo

Perform

RawToDataColumn

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

Scroll

ScrollBy

SendToBack

SetBounds

SetColumnAttributes

SetEditText

SetFocus

SetTextBuf

Show

StoreColumns

TCustomDBGrid

TimedScroll

TitleClick

Update

UpdateControlState

ValidFieldIndex


TCustomDBGrid::AcquireLayoutLock

TCustomDBGrid	See also

Calls BeginLayout if the table is not currently being reformatted.

bool __fastcall AcquireLayoutLock(void);

Description

Applications cannot call this protected method. AcquireLayoutLock is called before recomputing Columns when the fields in the dataset change or when the Columns property changes. AcquireLayoutLock returns true if the table is not already being laid out, to indicate that the computation of Columns should proceed. AcquireLayoutLock prevents the computation of Columns from looping endlessly because of the changes that must occur during the computation.


TCustomDBGrid::BeginLayout

TCustomDBGrid	See also

Increments the LayoutLock property when the column bindings or fields in the dataset change.

void __fastcall BeginLayout(void);

Description

Applications cannot call this protected method. Data-aware grids call BeginLayout internally before making changes to the Columns property or any of the individual TColumn objects in Columns. Once the change is complete, the data-aware grid calls EndLayout. If the response to the change must be canceled or postponed, the grid calls CancelLayout.

Each call to BeginLayout increments the LayoutLock property. Each call to EndLayout or CancelLayout decrements the LayoutLock property. If LayoutLock returns to 0 in a call to EndLayout, the Fields property is updated to match both the bindings of the Columns property and the fields available in the dataset. The Columns property is then updated in turn to match the Fields property. This ensures that the Columns property matches both the specified column bindings and the fields available in the dataset.


TCustomDBGrid::BeginUpdate

TCustomDBGrid	See also

Increments the UpdateLock property when the data in the grid changes.

void __fastcall BeginUpdate(void);

Description

Applications cannot call this protected method. Data-aware grids call BeginUpdate internally before making changes that affect the data that is drawn in the grid. Once the change is complete, the data-aware grid calls EndUpdate, which decrements the UpdateLock property.

While UpdateLock is greater than 0, the grid does not repaint its cells. BeginUpdate and EndUpdate prevent the grid from flickering when the grid is resized or the user scrolls through the data.


TCustomDBGrid::CancelLayout

TCustomDBGrid	See also

Decrements the LayoutLock property.

void __fastcall CancelLayout(void);

Description

Applications cannot call this protected method. Data-aware grids call CancelLayout internally when postponing the recomputation of Columns.

Each call to BeingLayout increments the LayoutLock property. Each call to EndLayout or CancelLayout decrements the LayoutLock property. If LayoutLock returns to 0 in a call to CancelLayout, the Columns property is not updated. CancelLayout is called from the DeferLayout method to decrement the LayoutLock and prevent the recomputation of Columns until a more appropriate time.


TCustomDBGrid::CanEditAcceptKey

TCustomDBGrid	See also

Indicates whether the Key parameter can be entered into the current cell.

DYNAMIC bool __fastcall CanEditAcceptKey(char Key);

Description

Data-aware grids use CanEditAcceptKey internally to determine whether keys typed by the user are valid for the field represented by the current cell. CanEditAcceptKey calls the IsValidChar method of the field component associated with the column that has input focus.

CanEditAcceptKey provides a crude validation of keyboard input. More refined validation is provided when the value in the cell is written to the record in the dataset, or by an edit mask.


TCustomDBGrid::CanEditModify

TCustomDBGrid	See also

Indicates whether the current column of the grid can be edited.

DYNAMIC bool __fastcall CanEditModify(void);

Description

Data-aware grids use CanEditModify internally to determine whether to allow the user to edit the current cell. CanEditModify returns true if the field in the current column can be edited. CanEditModify returns false if the field cannot be edited. If the dataset is not in edit mode, CanEditModify will attempt to put it in edit mode.

Note:	CanEditModify returns false when the current field is a binary large object (BLOB) field. BLOB fields can only be edited through the clipboard or by streaming.


TCustomDBGrid::CanEditShow

TCustomDBGrid	See also

Indicates whether the inplace edit control can be created to allow editing.

virtual bool __fastcall CanEditShow(void);

Description

TCustomDBGrid overrides the inherited method to prevent the inplace edit control from coming up while the layout of the grid is being recomputed.

Grid controls call CanEditShow internally before creating the editor for a cell. CanEditShow is called after the grid has determined that the field can be edited by calling CanEditModify.


TCustomDBGrid::CellClick

TCustomDBGrid	See also

Generates an OnCellClick event.

DYNAMIC void __fastcall CellClick(TColumn* Column);

Description

Applications cannot directly call CellClick. It is exposed as a protected method so that descendants can call the OnCellClick event handler in response to other events or override the response when the user releases the mouse in a cell of the grid.


TCustomDBGrid::ColEnter

TCustomDBGrid	See also

Generates an OnColEnter event.

DYNAMIC void __fastcall ColEnter(void);

Description

Applications cannot directly call ColEnter. It is exposed as a protected method so that descendants can call the OnCellEnter event handler in response to other events or override the response when a cell in the grid is selected.


TCustomDBGrid::ColExit

TCustomDBGrid	See also

Generates an OnColExit event.

DYNAMIC void __fastcall ColExit(void);

Description

Applications cannot directly call ColExit. It is exposed as a protected method so that descendants can call the OnColExit event handler in response to other events or override the response when a cell in the grid loses focus.


TCustomDBGrid::ColumnMoved

TCustomDBGrid	See also

Generates an OnColumnMoved event.

DYNAMIC void __fastcall ColumnMoved(int FromIndex, int ToIndex);

Description

Applications cannot directly call ColumnMoved. It is exposed as a protected method so that descendants can call the OnColumnMoved event handler in response to other events or override the response after a column in the grid is moved.


TCustomDBGrid::ColWidthsChanged

TCustomDBGrid	See also

Updates the column widths in the Columns property when the user resizes the columns.

DYNAMIC void __fastcall ColWidthsChanged(void);

Description

Applications cannot directly call ColWidthsChanged. It is called automatically when the user resizes the columns in the grid. ColWidthsChanged overrides the inherited method to update the column widths in the Columns property.


TCustomDBGrid::TCustomDBGrid

TCustomDBGrid	See also

Creates and initializes an instance of TCustomDBGrid.

__fastcall virtual TCustomDBGrid(Classes::TComponent* AOwner);

__fastcall TCustomDBGrid(HWND ParentWindow) : Grids::TCustomGrid(ParentWindow) { }

Description

Do not call TCustomDBGrid directly. Instead, instantiate a descendant of TCustomDBGrid such as TDBGrid. Grids placed on a form at design time are created automatically. When instantiating a grid at runtime, use the new keyword to create an indirect reference to the object.

Pass a single Component as a parameter to provide the grid with an Owner that is responsible for freeing the grid. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the grid in a non-VCL window. This syntax is used when the grid is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TCustomDBGrid creates the helper objects used by the data-aware grid and initializes

•	Color to clWindow, and ParentColor to false.

•	DefaultDrawing to true.

•	Options to include dgEditing, dgTitles, dgIndicator, dgColumnResize, dgColLines, dgRowLines, dgTabs, dgConfirmDelete, and dgCancelOnExit.


TCustomDBGrid::TCustomDBGrid
TCustomDBGrid::CreateColumns

TCustomDBGrid	See also

Creates the TDBGridColumns object that stores the column descriptors for the grid.

DYNAMIC TDBGridColumns* __fastcall CreateColumns(void);

Description

Applications cannot call CreateColumns. It is exposed as a protected method so that component writers can substitute a descendant of TDBGridColumns to manage the column descriptors of a data-aware grid.


TCustomDBGrid::TCustomDBGrid
TCustomDBGrid::CreateEditor

TCustomDBGrid	See also

Creates the inplace editor that allows the cells of the grid to be edited.

virtual Grids::TInplaceEdit* __fastcall CreateEditor(void);

Description

CreateEditor overrides the inherited method to create a data-aware descendant of TInplaceEdit.


TCustomDBGrid::TCustomDBGrid
TCustomDBGrid::CreateWnd

TCustomDBGrid	See also

Creates the window used to display the data-aware grid.

virtual void __fastcall CreateWnd(void);

Description

The Windows control for the grid can be temporarily destroyed and recreated in order to set properties that require changing the window creation parameters.  TCustomDBGrid calls CreateWnd to create this Windows control when necessary.

CreateWnd overrides the inherited method to set up the relationship between the visual display and the data source after the window is created.


TCustomDBGrid::DataToRawColumn

TCustomDBGrid	See also

Converts a column index in the Columns property to the index of the corresponding column in the visual display.

int __fastcall DataToRawColumn(int ACol);

Description

Applications cannot call this protected method. It is used internally to allow the data-aware grid to adjust to the presence or absence of the column that contains the row indicator.


TCustomDBGrid::DefaultDrawColumnCell

TCustomDBGrid	See also

Draws the text in a column cell.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

void __fastcall DefaultDrawColumnCell(const Windows::TRect &Rect, int DataCol, TColumn* Column, Grids::TGridDrawState State);

Description

Call DefaultDrawColumnCell from an OnDrawColumnCell event handler to lookup up the text representation of a field and write it to the cell. DefaultDrawColumnCell does exactly what the grid does when the DefaultDrawing property is true, except it never draws a focus rectangle on selected cells.

The Rect parameter is the position of the cell on the canvas. The DataCol parameter is the index of the column in the Columns array. The Column parameter is the TColumn object that describes the display attributes and field binding for the cell. The State parameter indicates whether the cell has input focus, whether the cell is selected, and whether the cell is a fixed (non-data) cell such as a column header.


TCustomDBGrid::DefaultDrawDataCell

TCustomDBGrid	See also

Draws the text in a column cell.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

void __fastcall DefaultDrawDataCell(const Windows::TRect &Rect, Db::TField* Field, Grids::TGridDrawState State);

Description

Call DefaultDrawDataCell from an OnDrawDataCell event handler to lookup up the text representation of a field and write it to the cell. Unlike what the grid draws when the DefaultDrawing property is true, DefaultDrawDataCell gets the alignment for the text from the field component rather than the column descriptor, and it never draws a focus rectangle on selected cells.

The Rect parameter gives the position of the cell on the canvas. The Field parameter gives the field component that provides the data and alignment for the cell. The State parameter indicates whether the cell has input focus, whether the cell is selected, and whether the cell is a fixed (non-data) cell such as a column header.


TCustomDBGrid::DefaultHandler

TCustomDBGrid	See also

Displays the popup menu when a column is right-clicked.

virtual void __fastcall DefaultHandler(void *Msg);

Description

DefaultHandler is the last method to receive Windows messages that are sent to the grid. After calling the inherited method and allowing it to process the message, DefaultHandler checks if the Msg parameter indicates the right mouse button was released over a column with a popup menu. If the column has a popup menu with its AutoPopup property set to true, DefaultHandler displays the popup menu.

When overriding DefaultHandler, be sure to call the inherited method for all unhandled messages.


TCustomDBGrid::DeferLayout

TCustomDBGrid	See also

Decrements the LayoutLock property and posts a message to the grid to trigger a new layout sequence at a more appropriate time.

void __fastcall DeferLayout(void);

Description

Applications cannot call this protected method. Data-aware grids call DeferLayout internally to postpone the recomputation of the Columns property after the dataset changes when it is inappropriate to recompute columns immediately.

DeferLayout calls CancelLayout to decrement the LayoutLock property which was incremented in response to the change in the dataset. It then posts a message to the grid which will trigger another layout attempt at a later point in time. When the message is received, the grid calls BeginLayout and then either EndLayout or DeferLayout, depending on whether it is an appropriate time to proceed with the computation of Columns.


TCustomDBGrid::DefineFieldMap

TCustomDBGrid	See also

Builds the Fields array from the Columns property and the data source.

virtual void __fastcall DefineFieldMap(void);

Description

Applications cannot call this protected method. DefineFieldMap rebuilds the Fields array to reflect the fields from the data source that correspond to the columns in the Columns property. After calling DefineFieldMap, the Columns property should be updated to use the field components in the Fields array. This ensures that the Columns property reflects any changes imposed by the dataset.


TCustomDBGrid::DefineProperties

TCustomDBGrid	See also

Defines a savable version of the Columns property when necessary.

virtual void __fastcall DefineProperties(Classes::TFiler* Filer);

Description

DefineProperties overrides the inherited method to load and save the Columns property if the columns have been customized.


TCustomDBGrid::~TCustomDBGrid

TCustomDBGrid	See also

Destroys an instance of TCustomDBGrid.

__fastcall virtual ~TCustomDBGrid(void);

Description

Do not call ~TCustomDBGrid directly in an application. Instead, use the delete keyword, which frees an instance of TCustomDBGrid given an indirect reference. ~TCustomDBGrid frees all the helper objects used by the grid.


TCustomDBGrid::DrawCell

TCustomDBGrid	See also

Draws the cell specified by the ACol and ARow parameters.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

virtual void __fastcall DrawCell(int ACol, int ARow, const Windows::TRect &ARect, Grids::TGridDrawState AState);

Description

DrawCell overrides the inherited method to use the Columns property when drawing cells in the grid.

DrawCell sets up the font and brush and paints the background of the cell. If the DefaultDrawing property is true, DrawCell fetches the data for the cell and writes it to the position described by the ARect parameter. Whether DefaultDrawing is true or false, DrawCell generates the OnDrawDataCell and OnDrawColumnCell events. Finally, if DefaultDrawing is true and either the cell has focus or the cell is selected and Options includes dgAlwaysShowSelection, DrawCell draws a focus rectangle around the cell.


TCustomDBGrid::DrawColumnCell

TCustomDBGrid	See also

Generates an OnDrawColumnCell event.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

DYNAMIC void __fastcall DrawColumnCell(const Windows::TRect &Rect, int DataCol, TColumn* Column, Grids::TGridDrawState State);

Description

Applications cannot call DrawColumnCell directly. It is exposed as a protected method so that descendants can call the OnDrawColumnCell event handler or override the method to block the event.


TCustomDBGrid::DrawDataCell

TCustomDBGrid	See also

Generates an OnDrawDataCell event.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

DYNAMIC void __fastcall DrawDataCell(const Windows::TRect &Rect, Db::TField* Field, Grids::TGridDrawState State);

Description

Applications cannot call DrawDataCell directly. It is exposed as a protected method so that descendants can call the OnDrawDataCell event handler or override the method to block the event.


TCustomDBGrid::EditButtonClick

TCustomDBGrid	See also

Generates an OnEditButtonClick event.

DYNAMIC void __fastcall EditButtonClick(void);

Description

Applications cannot call EditButtonClick directly. It is exposed as a protected method so that descendants can call the OnEditButtonClick event handler or override the method to block the event.


TCustomDBGrid::EndLayout

TCustomDBGrid	See also

Decrements the LayoutLock property and recomputes the Columns property if LayoutLock reaches 0.

void __fastcall EndLayout(void);

Description

Applications cannot call this protected method. Data-aware grids call Endlayout internally after changes to the Columns property or the dataset. EndLayout decrements the LayoutLock property which was previously incremented by BeingLayout before the Columns property was changed or when notification of the change to the dataset was received.

If LayoutLock returns to 0, EndLayout updates the Fields property to match both the bindings of the Columns property and the fields available in the dataset. The Columns property is then updated in turn to match the Fields property. This ensures that the Columns property matches both the specified column bindings and the fields available in the dataset.


TCustomDBGrid::EndUpdate

TCustomDBGrid	See also

Decrements the UpdateLock property.

void __fastcall EndUpdate(void);

Description

Applications cannot call this protected method. Data-aware grids call EndUpdate internally after making changes that affect the data that is drawn in the grid. EndUpdate returns the UpdateLock to the state it was in before the BeginUpdate method was called at the start of the changes.

While UpdateLock is greater than 0, the grid does not repaint its cells. When UpdateLock returns to 0, painting is reenabled. BeginUpdate and EndUpdate prevent the grid from flickering when the grid is resized or the user scrolls through the data.


TCustomDBGrid::GetColField

TCustomDBGrid	See also

Returns the field component that represents the binding of a specified column.

Db::TField* __fastcall GetColField(int DataCol);

Description

Call GetColField to obtain the field component for a column in the data-aware grid. The DataCol parameter is the index of the column in the Columns property, where 0 is the first column, 1 is the second column, and so on.

Unlike the Fields property, GetColField will return field components for columns that do not represent fields in the dataset, such as calculated fields.


TCustomDBGrid::GetEditLimit

TCustomDBGrid	See also

Limits the number of characters that can be typed into cells representing string fields.

DYNAMIC int __fastcall GetEditLimit(void);

Description

GetEditLimit is called by the inplace editor to determine if a limit should be placed on the number of characters a user can type into a cell. GetEditLimit sets no limits except when the selected cell represents a string field.


TCustomDBGrid::GetEditMask

TCustomDBGrid	See also

Returns the input mask associated with the field for the selected cell.

DYNAMIC System::AnsiString __fastcall GetEditMask(int ACol, int ARow);

Description

The inplace editor calls GetEditMask to obtain any input mask associated with the field binding of the indicated cell. GetEditMask returns the EditMask property of the field component from the Columns array.

The ACol and ARow parameters indicate the index of the row and column of the cell in the grid. The ACol parameter is not the same as the index of the column in the Columns array if the Options property includes dgIndicator.


TCustomDBGrid::GetEditText

TCustomDBGrid	See also

Returns the value of the indicated cell formatted for editing.

DYNAMIC System::AnsiString __fastcall GetEditText(int ACol, int ARow);

Description

The inplace editor calls GetEditText to obtain the text for the indicated cell. GetEditText locates the field component for the cell from the Columns array and returns its value formatted for editing.

The ACol and ARow parameters indicate the index of the row and column of the cell in the grid. The ACol parameter is the “raw” column index, which is not the same as the index of the column in the Columns array if the Options property includes dgIndicator.

Note:	The string returned by GetEditText may differ from the string returned by the GetFieldValue method if the field formats its value differently for editing and display.


TCustomDBGrid::GetFieldValue

TCustomDBGrid	See also

Returns the value of the indicated cell formatted for display.

System::AnsiString __fastcall GetFieldValue(int ACol);

Description

Call GetFieldValue to obtain the text that should be displayed in a cell. For example, an OnDrawColumnCell event handler can use GetFieldValue to obtain the text for the cell to draw it in a special way, rather than calling DefaultDrawColumnCell.

The ACol parameter is the index of the column in the columns array. If the Options property includes dgIndicator, this is not the same as the index of the column in the physical display.


TCustomDBGrid::HighlightCell

TCustomDBGrid	See also

Indicates whether a specified cell should be highlighted when it is drawn.

enum Grids__3 { gdSelected, gdFocused, gdFixed };

typedef Set<Grids__3, gdSelected, gdFixed> TGridDrawState;

virtual bool __fastcall HighlightCell(int DataCol, int DataRow, const System::AnsiString Value, Grids::TGridDrawState AState);

Description

Applications cannot call this protected method. It is called internally by the DrawCell method to determine whether the cell specified by the DataCol and DataRow parameters should be highlighted. HighlightCell returns true if the cell has focus, the cell is selected and Options includes dgAlwaysShowSelection, or the cell is in a selected row and Options includes dgRowSelect.


TCustomDBGrid::KeyDown

TCustomDBGrid	See also

Provides special processing when the user presses down on a key.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

Applications cannot call KeyDown. It is called automatically when the user presses a key, before the KeyPress method is called.

KeyDown generates an OnKeyDown event and then responds to the following keystrokes:

Keystroke	Response

UpArrow	Move to the previous row. If Options includes dgRowSelect, select it.

Ctrl+UpArrow	Move to the first row in the grid. Deselect any selected rows.

DownArrow	Move to the next row. If Options includes dgRowSelect, select it.

Ctrl+DownArrow	Move to the last row in the grid. Deselect any selected rows.

PageUp	Move up by the number of records shown in the grid. Deselect any selected rows.

Ctrl+PageUp	Move to the first row in the grid. Deselect any selected rows.

PageDown	Move down by the number of records shown in the grid. Deselect any selected rows.

LeftArrow	Move left one column. If Options includes dgRowSelect, move to the previous row without selecting it.

Ctrl+LeftArrow	Move to the first column in the current row.

RightArrow	Move right one column. If Options includes dgRowSelect, move to the next row without selecting it.

Ctrl+RightArrow	Move to the last column in the current row.

Home	Move to the first column of the current row. If Options includes dgRowSelect or the grid has only one column, move to the first record in the dataset. Deselect any selected rows.

Ctrl+Home	Move to the first record in the dataset. Deselect any selected rows.

End	Move to the last column of the current row. If Options includes dgRowSelect or the grid has only one column, move to the last record in the dataset. Deselect any selected rows.

Ctrl+End	Move to the last record in the dataset. Deselect any selected rows.

Tab	Move to the next cell in the grid.

Shift+Tab	Move to the previous cell in the grid.

Ctrl+Delete	Delete the current selection.

Insert	Insert a new row above the current one, and move to it. Deselect any selected rows.

Escape	Cancel any unposted edits. Deselect any selected rows.

F2	Put the grid in edit mode.


TCustomDBGrid::KeyPress

TCustomDBGrid	See also

Responds when the user presses a key.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

When the user presses a key, first the KeyDown method is called, then the KeyPress method, and finally the KeyUp method when the user releases the key. KeyPress overrides the inherited method to post edits to the database when the user presses Return.


TCustomDBGrid::LayoutChanged

TCustomDBGrid	See also

Recomputes the Columns property.

virtual void __fastcall LayoutChanged(void);

Description

Applications cannot call this protected method. It is called automatically in response to changes the affect the layout of the columns. These include

•	Changes to the fields in the dataset.

•	Changes in the Options property that affect the layout.

•	Changes to the TitleFont property.

LayoutChanged calls AcquireLayoutLock to initiate the changes to Columns. If AcquireLayoutLock does not indicate that the call to LayoutChanged is recursive, LayoutChanged calls EndLayout to perform the actual computation.


TCustomDBGrid::LinkActive

TCustomDBGrid	See also

Recomputes the Columns property and the vertical scrollbar of the grid.

virtual void __fastcall LinkActive(bool Value);

Description

Applications cannot call this protected method. It is called automatically when the dataset is opened. LinkActive calls LayoutChanged to recompute the Columns property, and adjusts the vertical scrollbar for the data in the dataset.


TCustomDBGrid::Loaded

TCustomDBGrid	See also

Sets up the Columns property once the data grid and all its child components are loaded.

virtual void __fastcall Loaded(void);

Description

Applications cannot call this protected method. Loaded overrides the inherited method to lay out the grid once all of its parts have been loaded.


TCustomDBGrid::MouseDown

TCustomDBGrid	See also

Provides special processing when the user clicks on the mouse.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall MouseDown(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

MouseDown is called automatically when the user presses the mouse button. If the mouse is pressed in the row or column resize region of the grid, MouseDown posts any pending edits and calls the inherited method to handle the resize. When Options includes dgRowSelect, MouseDown selects the row that received the click, or toggles its selection state if the Ctrl key is pressed. If the mouse is clicked in a data cell, MouseDown tries to put the grid into edit mode.


TCustomDBGrid::MouseUp

TCustomDBGrid	See also

Provides special processing when the user releases the mouse button.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall MouseUp(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

MouseUp is called automatically when the user releases the mouse button. After calling the inherited method, MouseUp locates the cell which was under the mouse when it was released. MouseUp generates an OnTitleClick or OnCellClick event, depending on the location of the mouse.


TCustomDBGrid::Notification

TCustomDBGrid	See also

Responds to notifications that components are about to be destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the inherited method, Notification

•	Checks if the pop-up menu for any of its columns is going away, and if so, resets the PopupMenu property of the column object.

•	Checks if the data source is going away, and if so, sets the DataSource property to NULL.

•	Checks if any of the field components associated with its columns is going away, and if so, removes the column from the layout.


TCustomDBGrid::RawToDataColumn

TCustomDBGrid	See also

Converts the index of a column in the visual display to the corresponding index in the Columns property.

int __fastcall RawToDataColumn(int ACol);

Description

Applications cannot call this protected method. It is used internally to allow the data-aware grid to adjust to the presence or absence of the column that contains the row indicator.


TCustomDBGrid::Scroll

TCustomDBGrid	See also

Updates the image of the grid to reflect a new record position.

virtual void __fastcall Scroll(int Distance);

Description

Scroll is called in response to changes in the current record in the dataset. Scroll updates the image in the grid, scrolling the data if necessary.


TCustomDBGrid::SetColumnAttributes

TCustomDBGrid	See also

Sets the column widths and disables tabbing to cells that can’t be edited.

virtual void __fastcall SetColumnAttributes(void);

Description

Applications cannot call this protected method. It is called automatically when the Columns property is recomputed, to adjust the column widths and ensure that the user can only tab to fields that can be edited.


TCustomDBGrid::SetEditText

TCustomDBGrid	See also

Updates the edited version of the current cell’s data.

DYNAMIC void __fastcall SetEditText(int ACol, int ARow, const System::AnsiString Value);

Description

SetEditText is called by the inplace editor so that the grid can store the new value for the current cell. The grid stores this value until the user moves to a new cell or presses Escape. If the user moves to a new cell, this value is written to the record in the database. If the user presses Escape, the value is discarded.


TCustomDBGrid::StoreColumns

TCustomDBGrid	See also

Indicates whether the columns of the grid are stored when the grid is saved, or whether they are generated dynamically.

bool __fastcall StoreColumns(void);

Description

StoreColumns causes the Columns property to be stored only when the Columns property has a State property of csCustomized. The State property for Columns indicates whether the columns are generated automatically from the fields in the dataset, or if they are specified programmatically or by the Columns editor.


TCustomDBGrid::TimedScroll

TCustomDBGrid	See also

Moves the current record in response to the user dragging the mouse outside of the data cells.

enum Grids__4 { sdLeft, sdRight, sdUp, sdDown };

typedef Set<Grids__4, sdLeft, sdDown>  TGridScrollDirection;

DYNAMIC void __fastcall TimedScroll(Grids::TGridScrollDirection Direction);

Description

If the Direction parameter includes sdUp, TimedScroll moves the dataset to the first visible record in the grid. If the Direction parameter includes sdDown, TimedScroll moves the dataset to the last visible record in the grid. After adjusting the current record, TimedScroll calls the inherited method to update the image.


TCustomDBGrid::TitleClick

TCustomDBGrid	See also

Generates an OnTitleClick event.

DYNAMIC void __fastcall TitleClick(TColumn* Column);

Description

Applications cannot call TitleClick directly. It is exposed as a protected method so that descendants can call the OnTitleClick event handler or override the method to block the event.


TCustomDBGrid::ValidFieldIndex

TCustomDBGrid	See also

Indicates whether an index into the columns array refers to a valid field in the dataset.

bool __fastcall ValidFieldIndex(int FieldIndex);

Description

Call ValidFieldIndex to determine whether a column displays data from a field in the dataset. ValidFieldIndex returns true if the column is associated with a database field. ValidFieldIndex returns false if the column is a calculated field or if the field for the column is undefined.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGrid


TCustomEdit

Hierarchy	Properties	Methods	Events	See also

The TCustomEdit object is the abstract class from which all edit-box and memo controls are derived.

Unit

stdctrls

Description

TCustomEdit encapsulates the behavior common to all components for editing text by introducing methods and properties that provide

•	Basic text editing functions such as selecting text, modifying selected text, and case conversions.

•	Ability to respond to changes in the contents of the text.

•	Access control of the text for making it read-only or introducing a password character to hide the actual value.

Do not create instances of TCustomEdit. Use TCustomEdit as a base class when declaring control objects that permit the user to enter or modify text. Properties and methods of TCustomEdit provide basic behavior that descendent classes inherit as well as behavior that components can override to customize their behavior.


TCustomEdit properties

TCustomEdit	Alphabetically	Legend

In TCustomEdit

AutoSelect

AutoSize

BorderStyle

CanUndo

CharCase

HideSelection

MaxLength

Modified

OEMConvert

PasswordChar

ReadOnly

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomEdit properties

TCustomEdit	By object	Legend

Align

AutoSelect

AutoSize

BorderStyle

BoundsRect

Brush

CanUndo

CharCase

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

HideSelection

Hint

Left

MaxLength

Modified

Name

OEMConvert

Owner

Parent

ParentColor

ParentWindow

PasswordChar

ReadOnly

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TCustomEdit::AutoSelect

TCustomEdit	See also	Example

Determines whether all the text in the edit control is automatically selected when the control gets focus.

__property bool AutoSelect = {read=FAutoSelect, write=FAutoSelect, default=1};

Description

Set AutoSelect to select all the text when the edit control gets focus. AutoSelect only applies to single-line edit controls.

Use AutoSelect when the user is more likely to replace the text in the edit control than to append to it.


TCustomEdit::AutoSize

TCustomEdit	See also 	Example

Determines whether the height of the edit control automatically resizes to accommodate the text.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=1};

Description

Use AutoSize to make the edit control adjust its size automatically so the client area accommodates the height of the text. When AutoSize is false, the edit control has a fixed height. When AutoSize is true, the size of the control is readjusted whenever a change occurs that could affect the height of the control, such as a change to the font or border style.

Note:	AutoSize only adjusts the height of the edit control. Even with AutoSize set to true, text in the edit control may appear truncated if it extends beyond the width of the control.


TCustomEdit::BorderStyle

TCustomEdit	See also	Example

Determines whether the edit control has a single line border around the client area.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Use BorderStyle to affect the sharpness with which the client area of the edit control stands out. BorderStyle can have a value of either bsSingle or bsNone. If BorderSyle is bsSingle, the edit control has a single-line border around the client area. If BorderStyle is bsNone, there will be no border.

Note:	BorderStyle interacts with the Ctl3D property to create different visual effects. Try different combinations of the two properties to get the desired look.


TCustomEdit::CanUndo

TCustomEdit	See also

Indicates whether the edit control contains changes that can be backed out.

__property bool CanUndo = {read=GetCanUndo, nodefault};

Description

Read CanUndo to determine whether the user has made any changes to the text that can be undone by calling the Undo method.  This is useful when enabling or disabling menu items that correspond to these commands.


TCustomEdit::CharCase

TCustomEdit	See also	Example

Determines the case of the text within the edit control.

enum TEditCharCase { ecNormal, ecUpperCase, ecLowerCase };

__property TEditCharCase CharCase = {read=FCharCase, write=SetCharCase, default=0};

Description

Use CharCase to force the contents of the edit control to assume a particular case. The possible values of CharCase are as follows:

Value	Meaning

ecLowerCase	The text is converted to lowercase.

ecNormal	The text appears in mixed case. It is not forced into any case.

ecUpperCase	The text is converted to uppercase.

When CharCase is set to ecLowerCase or ecUpperCase, the case of characters is converted as the user types them into the edit control. Changing the CharCase property to ecLowerCase or ecUpperCase changes the actual contents of the text, not just the appearance. Any case information is lost and can’t be recaptured by changing CharCase to ecNormal.


TCustomEdit::HideSelection

TCustomEdit	See also	Example

Determines whether the visual indication of the selected text remains when focus shifts to another control.

__property bool HideSelection = {read=FHideSelection, write=SetHideSelection, default=1};

Description

Set HideSelection to false to provide visual feedback of the selected portion of the text even when the edit control does not have focus. Set HideSelection to true to show the selection only when the edit control has focus. HideSelection does not affect the actual value of the selection, only the visual indication. Always setting HideSelection to false can make forms with many edit controls look too busy.


TCustomEdit::MaxLength

TCustomEdit	See also	Example

Specifies the maximum number of characters the user can enter into the edit control.

__property int MaxLength = {read=FMaxLength, write=SetMaxLength, default=0};

Description

Use MaxLength to limit the number of characters that can be entered into the edit control. A value of 0 indicates that there is no application-defined limit on the length.

Use MaxLength to limit the length of the text in an edit control if that text will be copied into a fixed-length buffer.

Note:	Setting MaxLength will not truncate the existing text, it merely prevents the user from adding more text after reaching the limit of MaxLength characters.

Note:	Even when MaxLength is 0, there may be limitations imposed by the operating system on the number of characters that may be entered into an edit control.


TCustomEdit::Modified

TCustomEdit	See also	Example

Indicates whether the user edited the text of the edit control.

__property bool Modified = {read=GetModified, write=SetModified, nodefault};

Description

Use Modified to determine whether the Text property of the edit control changed. If an application directly alters the Text property of an edit control, it should set the Modified property to true.


TCustomEdit::OEMConvert

TCustomEdit	See also

Determines whether characters typed in the edit control are converted from ANSI to OEM and then back to ANSI.

__property bool OEMConvert = {read=FOEMConvert, write=SetOEMConvert, default=0};

Description

To ensure that any characters typed in the edit control can be unambiguously converted to the OEM character set, set OEMconvert to true. This causes all characters to be converted from ANSI to OEM and then back to ANSI as they are typed. Set OEMconvert to false to avoid the overhead of this conversion when it does not matter whether the text can be unambiguously mapped to an OEM string.

OEMConvert is most useful for edit controls used to enter file names when the application does not use Unicode file names.


TCustomEdit::PasswordChar

TCustomEdit	See also	Example

Indicates the character, if any, to display in place of the actual characters typed in the control.

__property char PasswordChar = {read=FPasswordChar, write=SetPasswordChar, default=0};

Description

Use the PasswordChar property to create an edit control that displays a special character in place of any entered text. If PasswordChar is set to the null character (ANSI character zero), the edit control displays its text normally. If PasswordChar is any other character, the edit control displays PasswordChar in place of each character typed. PasswordChar affects the appearance of the edit control only. The value of the Text property reflects the actual characters that are typed.


TCustomEdit::ReadOnly

TCustomEdit	See also	Example

Determines whether the user can change the text of the edit control.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, default=0};

Description

To restrict the edit control to display only, set the ReadOnly property to true. Set ReadOnly to false to allow the contents of the edit control to be edited.

Setting ReadOnly to true ensures that the text is not altered, while still allowing the user to select text. The selected text can then be manipulated by the application, or copied to the Clipboard.


TCustomEdit::SelLength

TCustomEdit	See also 	Example

Specifies the number of characters that are selected.

__property int SelLength = {read=GetSelLength, write=SetSelLength, nodefault};

Description

Read SelLength to determine the length, in characters, of the selected text. Set SelLength to change the selection to consist of the first SelLength characters starting at SelStart.

Note:	Setting SelLength to a value greater than the number of characters from SelStart to the end of the text results in the selection of all characters from SelStart to the end of the text. Reading SelLength immediately after setting it to a value greater than the number of available characters returns the number of characters actually selected, not the value that was just set.


TCustomEdit::SelStart

TCustomEdit	See also 	Example

Specifies the position of the first selected character in the text.

__property int SelStart = {read=GetSelStart, write=SetSelStart, nodefault};

Description

Read SelStart to determine the position of the first selected character, where 0 indicates the first character. If there is no selected text, SelStart indicates the position of the cursor. Set SelStart to remove the current selection and position the cursor just before the indicated character.

To select a particular range of the text, first set SelStart to position the cursor, and then set SelLength to extend the selection.


TCustomEdit::SelText

TCustomEdit	See also 	Example

Specifies the selected portion of the edit control’s text.

__property System::AnsiString SelText = {read=GetSelText, write=SetSelText};

Description

Read SelText to determine the value of the selected text. Set SelText to replace the selected text with a new string. If there is no selection, but the edit control has focus, set SelText to insert a new string into the text at the cursor.


TCustomEdit events

TCustomEdit	Alphabetically	Legend

In TCustomEdit

OnChange


TCustomEdit events

TCustomEdit	By object	Legend

OnChange


TCustomEdit::OnChange

TCustomEdit	See also

Occurs when the text for the edit control may have changed.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action whenever the text for the edit control may have changed. Use the Modified property to see if a change actually occurred. The Text property of the edit control will already be updated to reflect any changes. This event provides the first opportunity to respond to modifications that the user types into the edit control.


TCustomEdit methods

TCustomEdit	Alphabetically	Legend

In TCustomEdit

~TCustomEdit

Change

Clear

ClearSelection

ClearUndo

CopyToClipboard

CreateParams

CreateWnd

CutToClipboard

DestroyWnd

DoSetMaxLength

GetSelLength

GetSelStart

GetSelText

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelLength

SetSelStart

SetSelTextBuf

TCustomEdit

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomEdit methods

TCustomEdit	By object	Legend

~TCustomEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CreateParams

CreateWnd

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DestroyWnd

DisableAlign

Dispatch

DoSetMaxLength

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelLength

GetSelStart

GetSelText

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelLength

SetSelStart

SetSelTextBuf

SetTextBuf

Show

TCustomEdit

Undo

Update

UpdateControlState


TCustomEdit::Change

TCustomEdit	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(void);

Description

Applications do not call the Change method directly. It is triggered automatically by Windows events. Change is exposed as a protected method so that derived classes can make additional responses when the text changes beyond invoking the OnChange event handler. If Derived classes that override the Change method do not call the inherited method, the OnChange event handler will not be called.


TCustomEdit::Clear

TCustomEdit	See also

Deletes all text from the edit control.

virtual void __fastcall Clear(void);

Description

Use Clear to replace the Text property with an empty string. Clear removes all text, not just the selected text. To remove just the selected text, use ClearSelection.


TCustomEdit::ClearSelection

TCustomEdit	See also	Example

Removes the selected text from the edit control.

void __fastcall ClearSelection(void);

Description

Use ClearSelection to delete the selected text from the edit control. If no text is selected, ClearSelection does nothing. If all of the text is selected, ClearSelection clears all text, like the Clear method.

Note:	Calling ClearSelection does the same thing as sending the edit control a WM_CLEAR message.


TCustomEdit::ClearUndo

TCustomEdit	See also

Clears the undo buffer so that no changes to the text can be backed out.

void __fastcall ClearUndo(void);

Description

Use ClearUndo to commit changes to the Text property.  After calling ClearUndo, the CanUndo property is false and the Undo method does nothing.


TCustomEdit::CopyToClipboard

TCustomEdit	See also 	Example

Copies the selected text in the edit control to the Clipboard in CF_TEXT format.

void __fastcall CopyToClipboard(void);

Description

Use CopyToClipboard to replace the contents of the Clipboard with the selected text. CopyToClipbard does not clear the Clipboard if no text is selected. If no text is selected, CopyToClipboard does nothing.

Note:	Calling CopyToClipboard does the same thing as sending the edit control a WM_COPY message.


TCustomEdit::TCustomEdit

TCustomEdit	See also	Example

Creates an instance of TCustomEdit.

__fastcall virtual TCustomEdit(Classes::TComponent* AOwner);

__fastcall TCustomEdit(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not instantiate a TCustomEdit object. To add an edit control to a form, create an instance of a TCustomEdit descendant, using the new keyword.

Pass a single Component as a parameter to provide the edit control with an Owner that is responsible for freeing the edit control. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the edit control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TCustomEdit initializes

•	AutoSelect to true.

•	AutoSize to true.

•	BorderStyle to bsSingle.

•	ControlStyle to include csClickEvents, csDoubleClicks, csFixedHeight, and csSetCaption.

•	Height and Width to 25 and 121.

•	HideSelection to true.

•	ParentColor to false.

•	TabStop to true.


TCustomEdit::TCustomEdit
TCustomEdit::CreateParams

TCustomEdit	See also

Initializes a window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it passes to CreateWindowHandle. TCustomEdit overrides the inherited method to specify a scrollable single-line edit control that reflects the current values of the BorderStyle, HideSelections, PasswordChar, and ReadOnly properties.


TCustomEdit::TCustomEdit
TCustomEdit::CreateWnd

TCustomEdit	See also

Creates a Windows control corresponding to the edit control.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd is called when the edit control is created, and whenever a change to the edit control requires the window to be recreated. After calling the inherited method, CreateWnd sends the newly created window messages to enforce the MaxLength and PasswordChar properties.


TCustomEdit::CutToClipboard

TCustomEdit	See also 	Example

Copies the selected text to the Clipboard in CF_TEXT format and then deletes the selection.

void __fastcall CutToClipboard(void);

Description

Use CutToClipboard to replace the contents of the Clipboard with the selected text while clearing the selected text. If no text is selected, CutToClipboard does nothing.


TCustomEdit::~TCustomEdit
TCustomEdit::DestroyWnd

TCustomEdit	See also

Destroys the Windows control that corresponds to the edit control.

virtual void __fastcall DestroyWnd(void);

Description

The Windows control for the edit box can be temporarily destroyed and recreated in order to set properties that require changing the window creation parameters.  When this happens, DestroyWnd is called.

Before the window is destroyed, DestroyWnd saves a copy of any properties that are needed to recreate the window after it is destroyed.


TCustomEdit::DoSetMaxLength

TCustomEdit	See also

Sets the MaxLength property.

virtual void __fastcall DoSetMaxLength(int Value);

Description

DoSetMaxLength is the property access function for the MaxLength property. It is exposed as a protected method so that descendants of TCustomEdit can customize the implementation of the MaxLength property.

DoSetMaxLength sends an EM_LIMITTEXT message to the window of the edit control.


TCustomEdit::GetSelLength

TCustomEdit	See also

Returns the SelLength property.

virtual int __fastcall GetSelLength(void);

Description

GetSelLength is the property access function for the SelLength property. It is exposed as a protected method so that descendants of TCustomEdit can customize the implementation of the SelLength property.

GetSelLength sends an EM_GETSEL message to the window of the edit control and returns the difference between the starting position and the ending position.


TCustomEdit::GetSelStart

TCustomEdit	See also

Returns the SelStart property.

virtual int __fastcall GetSelStart(void);

Description

GetSelStart is the property access method for the SelStart property. It is exposed as a protected method so that descendants of TCustomEdit can customize the implementation of the SelStart property.

GetSelLength sends an EM_GETSEL message to the window of the edit control and returns the starting position.


TCustomEdit::GetSelText

TCustomEdit	See also

Returns the SelText property.

virtual System::AnsiString __fastcall GetSelText(void);

Description

GetSelText is the property access method for the SelText property. It is exposed as a protected method so that descendants of TCustomEdit can customize the implementation of the SelText property.


TCustomEdit::GetSelTextBuf

TCustomEdit	See also 	Example

Copies the selected text into a buffer and returns the number of characters copied.

virtual int __fastcall GetSelTextBuf(char * Buffer, int BufSize);

Description

Use GetSelTextBuf to copy the selected text into a character buffer. If there is no selection, the buffer receives an empty string. If the selection contains more than (BufSize - 1) characters, only the first (BufSize - 1) characters are copied. GetSelTextBuf returns the number of characters that were actually copied into the buffer.


TCustomEdit::PasteFromClipboard

TCustomEdit	See also	Example

Pastes the contents of the Clipboard into edit control, replacing the current selection.

void __fastcall PasteFromClipboard(void);

Description

Use PasteFromClipboard to replace the selected text with the contents of the Clipboard, or, if no text is selected, to insert the contents of the Clipboard at the cursor. If the Clipboard is empty, or if it does not contain anything in CF_TEXT format, PasteFromClipbard does nothing.

Note:	Calling PasteFromClipboard does the same thing as sending the edit control a WM_PASTE message.


TCustomEdit::SelectAll

TCustomEdit	See also 	Example

Selects all text in the edit control.

void __fastcall SelectAll(void);

Description

Use SelectAll to select all text in the edit control. To select only part of the text, use the SelStart and SelLength properties.


TCustomEdit::SetSelLength

TCustomEdit	See also

Sets the SelLength property.

virtual void __fastcall SetSelLength(int Value);

Description

SetSelLength is the property access method for the SelLength property. It is exposed as a protected method so that descendants of TCustomEdit can customize the implementation of the SelLength property.

SetSelLength sends an EM_SETSEL message to the window of the edit control, specifying a selection that begins at SelStart and ends at SelStart + Value.


TCustomEdit::SetSelStart

TCustomEdit	See also

Sets the SelStart property.

virtual void __fastcall SetSelStart(int Value);

Description

SetSelStart is the property access method for the SelStart property. It is exposed as a protected method so that descendants of TCustomEdit can customize the implementation of the SelStart property.

SetSelLength sends an EM_SETSEL message to the window of the edit control to position the cursor on the position indicated by Value.


TCustomEdit::SetSelTextBuf

TCustomEdit	See also	Example

Replaces the selected text with a null-terminated string.

void __fastcall SetSelTextBuf(char * Buffer);

Description

Use SetSelTextBuf to replace the current selection by the contents of the null-terminated string pointed to by Buffer. If no text is selected, the contents of Buffer are inserted at the cursor. SetSelTextBuf does the same thing as setting the SelText property, except that it takes a PChar rather than a string.


TCustomEdit::Undo

TCustomEdit	See also

Backs out all changes in the undo buffer.

void __fastcall Undo(void);

Description

Call ClearUndo to cancel all changes made to the Text property since the last call to the ClearUndo method. If ClearUndo was never called, Undo backs out all changes.

To determine whether there are any changes in the undo buffer, check the CanUndo property.


TCustomEdit::~TCustomEdit

TCustomEdit

Frees the memory associated with the TCustomEdit object.

__fastcall virtual ~TCustomEdit(void) { }

Description

Do not call ~TCustomEdit directly. Instead, use the delete keyword on the object, which causes ~TCustomEdit to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomForm

Hierarchy	Properties	Methods	Events	See also

TCustomForm is the abstract base class from which to derive a window such as a form or dialog.

Unit

forms

Description

Derive from TCustomForm to create a custom window. The TCustomForm descendant can contain other objects, such as TButton, TCheckBox, and TComboBox objects.


TCustomForm properties

TCustomForm	Alphabetically	Legend

In TCustomForm

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

BorderIcons

BorderStyle

Canvas

ClientHandle

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

FormStyle

HelpFile

Icon

KeyPreview

MDIChildCount

MDIChildren

Menu

ModalResult

ObjectMenuItem

OleFormObject

Parent

PixelsPerInch

Position

PrintScale

Scaled

TileMode

Visible

WindowMenu

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomForm properties

TCustomForm	By object	Legend

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

Align

AutoScroll

BorderIcons

BorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHandle

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

FormStyle

Handle

Height

HelpContext

HelpFile

Hint

HorzScrollBar

Icon

KeyPreview

Left

MDIChildCount

MDIChildren

Menu

ModalResult

Name

ObjectMenuItem

OleFormObject

Owner

Parent

ParentFont

ParentWindow

PixelsPerInch

PopupMenu

Position

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

TileMode

Top

VCLComObject

VertScrollBar

Visible

Width

WindowMenu

WindowProc

WindowState


TCustomForm::Active

TCustomForm	See also

Specifies whether the form has focus.

__property bool Active = {read=FActive, nodefault};

Description

Use Active to determine whether the form has focus.  The Active Form receives all keyboard input.  If it has a title bar, it is drawn using the active colors specified in the Control panel.

If Active is true , the form has focus; if Active is false, the form does not have focus.


TCustomForm::ActiveControl

TCustomForm	See also 	Example

Specifies the control that has focus on the form.

__property Controls::TWinControl* ActiveControl = {read=FActiveControl, write=SetActiveControl, stored=IsForm};

Description

Use ActiveControl to get or set the control that has focus on the form. Only one control can have focus at a given time in an application.

If the form does not have focus, ActiveControl is the control on the form that will receive focus when the form receives focus.

Note:	When focus shifts to another control, ActiveControl is updated before the OnExit event occurs.


TCustomForm::ActiveMDIChild

TCustomForm	See also 	Example

Specifies the MDI child that has focus.

__property TForm* ActiveMDIChild = {read=GetActiveMDIChild};

Description

Use ActiveMDIChild to get the MDI child that has focus.

If the form is not an MDI parent (that is, if the FormStyle property of the form is not fsMDIForm), ActiveMDIChild returns NULL.


TCustomForm::ActiveOleControl

TCustomForm	See also

Specifies the OLE control on the form that reacts to changes in focus.

__property Controls::TWinControl* ActiveOleControl = {read=FActiveOleControl, write=FActiveOleControl};

Description

Use ActiveOLEControl to get or set an OLE control on the form that reacts to changes in focus.

If ActiveOLEControl is not NULL, the user interface for the specified OLE control is deactivated when it is not focused. Also, when the form receives or loses focus, the document window for the specified OLE control is activated or deactivated respectively.


TCustomForm::BorderIcons

TCustomForm	See also 	Example

Specifies which icons appear on the title bar of the form.

enum TBorderIcon { biSystemMenu, biMinimize, biMaximize, biHelp };

typedef Set<TBorderIcon, biSystemMenu, biHelp> TBorderIcons;

__property TBorderIcons BorderIcons = {read=FBorderIcons, write=SetBorderIcons, stored=IsForm, default=7}

Description

Use BorderIcons to get or set the icons that appear on the title bar of the form. BorderIcons can include any of the following TBorderIcons values:

Value	Meaning

biSystemMenu	The form has a Control menu (also known as a System menu).

biMinimize	The form has a Minimize button

biMaximize	The form has a Maximize button

biHelp	If BorderStyle is bsDialog or biMinimize and biMaximize are excluded, a question mark appears in the form's title bar and when clicked, the cursor changes to crHelp; otherwise,no question mark appears.

Note:	Certain combinations of the BorderIcons and BorderStyle properties are mutually exclusive. For example, BorderIcons biMax, biMin with BorderStyle of bsDialog are mutually exclusive.


TCustomForm::BorderStyle

TCustomForm	See also

Specifies the appearance and behavior of the form border.

enum TFormBorderStyle { bsNone, bsSingle, bsSizeable, bsDialog, bsToolWindow, bsSizeToolWin };

__property TFormBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, stored=IsForm, default=2};

Description

Use BorderStyle to get or set the appearance and behavior of the form border. BorderStyle can be any of the following TFormBorderStyle values:

Value	Meaning

bsDialog	Not resizeable; standard dialog box border

bsSingle	Not resizeable; single-line border

bsNone	Not resizeable; no visible border line

bsSizeable	Standard resizeable border

bsToolWindow	like bsSingle but with a smaller caption

bsSizeToolWin	like bsSizeable with a smaller caption

Note:	Changing the border style of an MDI child form to bsDialog or bsNone has no effect.


TCustomForm::Canvas

TCustomForm	See also 	Example

Provides access to the drawing area of the form.

__property Graphics::TCanvas* Canvas = {read=GetCanvas};

Description

Use TCanvas to draw on the client area of the form. Canvas is often used in the OnPaint event handler.


TCustomForm::ClientHandle

TCustomForm	See also	Example

Provides access to the handle of the form’s internal MDI client window.

__property HWND ClientHandle = {read=FClientHandle, nodefault};

Description

Use ClientHandle to get the handle for the form’s internal MDI client window.

ClientHandle is meaningful only if the form is an MDI parent (that is, if the form’s FormStyle property is set to fsMDIForm).

Note:	Use the Handle property instead to get the handle to the form window itself.


TCustomForm::ClientHeight

TCustomForm	See also	Example

Specifies the height (in pixels) of the form’s client area.

__property ClientHeight = {write=SetClientHeight, stored=IsClientSizeStored};

Description

Use ClientHeight to determine the height (in pixels) of the form’s client area. The client area is the usable area inside the form's border.  Set ClientHeight to change the height of the form’s window based on the desired client area.  To change the height of the form’s window based on the total size of the window (including the border, menu, status bar and so on), use the Height property instead.


TCustomForm::ClientRect

TCustomForm	See also

Specifies the dimensions of the form’s client area.

__property Windows::TRect ClientRect = {read=GetClientRect};

Description

Use ClientRect to get or set the form’s client area. The client area is the usable area inside the form's border.

ClientRect is equivalent to Rect(0,0,ClientWidth, ClientHeight).


TCustomForm::ClientWidth

TCustomForm	See also 	Example

Specifies the width (in pixels) of the form’s client area.

__property ClientWidth  = {write=SetClientWidth, stored=IsClientSizeStored};

Description

Use ClientWidth to determine the width (in pixels) of the form’s client area. The client area is the usable area inside the form's border. Set ClientWidth to change the width of the form’s window based on the desired client area.  To change the width of the form’s window based on the total size of the window (including the border, status bar and so on), use the Width property instead.


TCustomForm::Designer

TCustomForm	See also

Specifies the designer for the form.

__property TDesigner* Designer = {read=FDesigner, write=SetDesigner};

Description

The Designer property is used internally at design time. Never assign a value to this property. This is done automatically by the form designer. Only use this property when designing classes for use in the form designer such as property editors and component editors.


TCustomForm::DropTarget

TCustomForm	See also

Specifies whether the form is the target of a drag-and-drop operation.

__property bool DropTarget = {read=FDropTarget, write=FDropTarget, nodefault};

Description

Use DropTarget to determine whether the form is currently the target of a drag-and-drop operation.


TCustomForm::FormStyle

TCustomForm	See also	Example

Determines the form’s style.

enum TFormStyle { fsNormal, fsMDIChild, fsMDIForm, fsStayOnTop };

__property TFormStyle FormStyle = {read=FFormStyle, write=SetFormStyle, stored=IsForm, default=0};

Description

Use FormStyle to get or set the form’s style. FormStyle is one of the following values:

Value	Meaning

fsNormal	The form is neither an MDI parent window nor an MDI child window.

fsMDIChild	The form is an MDI child window.

fsMDIForm	The form is an MDI parent window.

fsStayOnTop	This form remains on top of the desktop and of other forms in the project, except any others that also have FormStyle set to fsStayOnTop.

If the form is the main form of an MDI application, its FormStyle property must be set to fsMDIForm.

Note:	It is not advisable to change FormStyle at runtime.


TCustomForm::HelpFile

TCustomForm	See also

Specifies the name of the file the application uses to display Help.

__property System::AnsiString HelpFile = {read=FHelpFile, write=FHelpFile};

Description

Use HelpFile for forms that have a help file to use with the Windows Help system. Windows selects Help topics from the specified file.


TCustomForm::Icon

TCustomForm	See also 	Example

Specifies the icon that appears when the form is minimized.

__property Graphics::TIcon* Icon = {read=FIcon, write=SetIcon, stored=IsIconStored};

Description

Set the Icon property to provide an icon for the form. If Icon is not set, Windows provides a default icon when the form is minimized.


TCustomForm::KeyPreview

TCustomForm	See also 	Example

Specifies whether the form should receive keyboard events before the active control.

__property bool KeyPreview = {read=FKeyPreview, write=FKeyPreview, stored=IsForm, default=0};

Description

If KeyPreview is true, keyboard events occur on the form before they occur on the active control. (The active control is specified by the ActiveControl property.)

If KeyPreview is false, keyboard events occur only on the active control.

Navigation keys (Tab, BackTab, the arrow keys, and so on) are unaffected by KeyPreview because they do not generate keyboard events.

KeyPreview is false by default.


TCustomForm::MDIChildCount

TCustomForm	See also 	Example

Specifies the number of open MDI child forms.

__property int MDIChildCount = {read=GetMDIChildCount, nodefault};

Description

Use MDIChildCount to get the number of open MDI child forms.

MDIChildCount is meaningful only if the form is an MDI parent (that is, if the form’s FormStyle property is set to fsMDIForm).


TCustomForm::MDIChildren

TCustomForm	See also 	Example

Provides indexed access to all MDI child forms.

__property TForm* MDIChildren[int I] = {read=GetMDIChildren};

Description

Use MDIChildren to access a child form.

I is the index of the child form to access. The index of the most recently created MDI child is always 0, and the index of the first-created MDI child is always MDIChildCount - 1 (the MDIChildren array is reverse-order of MDI child creation).

MDIChildren is meaningful only if the form is an MDI parent (that is, if the form’s FormStyle property is set to fsMDIForm).


TCustomForm::Menu

TCustomForm	See also	Example

Specifies the form’s main menu.

__property Menus::TMainMenu* Menu = {read=FMenu, write=SetMenu, stored=IsForm};

Description

Use Menu to get or set the form’s main menu. At design time, Menu is set to the first TMainMenu component added to the form.


TCustomForm::ModalResult

TCustomForm	See also 	Example

Represents the return value of a form that is used as a modal dialog.

typedef int TModalResult;

__property TModalResult ModalResult = {read=FModalResult, write=FModalResult, nodefault};

Description

Use ModalResult to close the form when it is displayed modally.

By default, ModalResult is mrNone. Set ModalResult to any nonzero value to close the form. The value assigned to ModalResult becomes the return value of the ShowModal function call used to display the form.

Note:	This property is modified automatically by some components such as the TButton object. See TButton::ModalResult for details.

ModalResult can be one of the following TModalResult values:

Constant	Value

mrNone	0

mrOk	idOK

mrCancel	idCancel

mrAbort	idAbort

mrRetry	idRetry

mrIgnore	idIgnore

mrYes	idYes

mrNo	idNo

mrAll	mrNo + 1


TCustomForm::ObjectMenuItem

TCustomForm	See also

Represents an OLE object menu item that reacts to selections of OLE objects.

__property Menus::TMenuItem* ObjectMenuItem = {read=FObjectMenuItem, write=SetObjectMenuItem, stored=IsForm};

Description

Use ObjectMenuItem to get or set a menu item that becomes enabled or disabled when an OLE object on the form is selected or unselected respectively.

The OLE object menu item can be used for standard OLE commands, such as Activate or Convert. (The implementations of these commands are provided by the OLE server.)


TCustomForm::OleFormObject

TCustomForm	See also

Specifies the IOleForm interface for an in-place OLE object contained in the form.

__property _di_IOleForm OleFormObject = {read=FOleForm, write=FOleForm};

Description

OleFormObject is used to communicate resize and destroy notifications when a form is used as a frame for an in-place OLE object.


TCustomForm::Parent

TCustomForm	See also

Specifies the windowed control that contains the form.

__property TWinControl* Parent = {read=FParent, write=SetParent};

Description

Use the Parent property to embed the form in another control (usually another form). Changing the Parent property moves the form to a new container.

Many forms do not have a Parent. For example, forms that appear directly on the Windows desktop have Parent set to NULL.


TCustomForm::PixelsPerInch

TCustomForm	See also

Represents the proportion of the font on the system on which the form was designed.

__property int PixelsPerInch = {read=GetPixelsPerInch, write=SetPixelsPerInch, stored=false, nodefault};

Description

Use PixelsPerInch at runtime to change how the form is scaled to the current screen resolution. If PixelsPerInch is changed from its default value, the form will not have the same proportion on every screen resolution.

At design time, PixelsPerInch is set automatically when the form is saved. Changes to PixelsPerInch made in the Object Inspector only affect the form at runtime.

The form’s Scaled property must be true for PixelsPerInch to have an effect.


TCustomForm::Position

TCustomForm	See also

Represents the size and placement of the form.

enum TPosition { poDesigned, poDefault, poDefaultPosOnly, poDefaultSizeOnly, poScreenCenter };

__property TPosition Position = {read=FPosition, write=SetPosition, stored=IsForm, default=0};

Description

Use Position to get or set the size and placement of the form. Position can have one of the following TPosition values:

Value	Meaning

poDesigned	The form appears positioned on the screen and with the same height and width as it had at design time.

poDefault	The form appears in a position on the screen and with a height and width determined by Windows. Each time you run the application, the form moves slightly down and to the right. The right side of the form is always near the far right side of the screen, and the bottom of the form is always near the bottom of the screen, regardless of the screen's resolution.

poDefaultPosOnly	The form displays with the size you created it at design time, but Windows chooses its position on the screen. Each time you run the application, the form moves slightly down and to the right. When the form can no longer move down and to the right and keep the same size while remaining entirely visible on the screen, the form displays at the top-left corner of the screen.

poDefaultSizeOnly	The form appears in the position you left it at design time, but Windows chooses its size. The right side of the form is always near the far right side of the screen, and the bottom of the form is always near the bottom of the screen, regardless of the screen's resolution.

poScreenCenter	The form remains the size you left it at design time, but is positioned in the center of the screen.


TCustomForm::PrintScale

TCustomForm	See also	Example

Represents the proportions of a printed form.

enum TPrintScale { poNone, poProportional, poPrintToFit };

__property TPrintScale PrintScale = {read=FPrintScale, write=FPrintScale, stored=IsForm, default=1};

Description

Use PrintScale to get or set the proportions of the printed form. PrintScale can have one of the following TPrintScale values:

Value	Meaning

poNone	No special scaling occurs; therefore, the printed form and how the form appears onscreen may appear squished or stretched.

poProportional	The form is printed so that the printed image is approximately the same visible size as on the screen (WYSIWYG). The form image is scaled so that the printed image is approximately the same visible size as on the screen.

poPrintToFit	The form is printed using the same screen proportions, but in a size that just fits the printed page.


TCustomForm::Scaled

TCustomForm	See also

Specifies whether the form is sized according to the value of the PixelsPerInch property.

__property bool Scaled = {read=GetScaled, write=SetScaled, stored=IsForm, default=1};

Description

If Scaled is true, and the value of PixelsPerInch differs from the current system settings, the form is scaled to a new size. If Scaled is false, no scaling occurs.


TCustomForm::TileMode

TCustomForm	See also	Example

Represents how MDI child forms are arranged when the Tile method is called.

enum TTileMode { tbHorizontal, tbVertical };

__property TTileMode TileMode = {read=FTileMode, write=FTileMode, default=0};

Description

TileMode can have one of the following TTileMode values:

Value	Meaning

tbHorizontal	Each form stretches across the width of the parent form

tbVertical	Each form stretches along the height of the parent form

TileMode is meaningful only if the form is an MDI child (that is, if the form’s FormStyle property is set to fsMDIChild).


TCustomForm::Visible

TCustomForm	See also 	Example

Indicates whether the form is visible.

__property Visible  = {write=SetVisible, default=0};

Description

Use Visible to determine whether the form is visible.

If Visible is true, the form is visible unless it is completely obscured by other forms. If Visible is false, the form is not visible.

The Show and ShowModal methods set Visible to true and bring the form to the front of all open windows.


TCustomForm::WindowMenu

TCustomForm	See also	Example

Specifies the Window menu for an MDI parent form.

__property Menus::TMenuItem* WindowMenu = {read=FWindowMenu, write=SetWindowMenu, stored=IsForm};

Description

Use WindowMenu to get or set the Window menu for an MDI parent form. The Window menu is a standard menu in MDI applications. It contains commands that let the user manage the windows in the application. Menu items usually include Cascade, Arrange Icons, Tile, and so on.

The Window menu also lists (at the bottom) the child windows that are currently open in the application. When the user selects one of these windows from the menu, the window becomes the active window in the application.

Although this menu is commonly called the Window menu, it can have any name that corresponds to an existing menu item on the menu bar. The names of open child forms are merged onto the menu automatically at run-time.

WindowMenu is meaningful only if the form is an MDI parent (that is, if the form’s FormStyle property is set to fsMDIForm).


TCustomForm::WindowState

TCustomForm	See also 	Example

Represents how the form appears on the screen.

enum TWindowState { wsNormal, wsMinimized, wsMaximized };

__property TWindowState WindowState = {read=FWindowState, write=SetWindowState, stored=IsForm, default=0};

Description

Use WindowMenu to get or set whether the form appears on the screen in its minimized, maximized, or normal state.

WindowState can have one of the following TWindowState values:

Value	Meaning

wsNormal	The form appears in its normal state (that is, its non-minimized, non-maximized state).

wsMinimized	The form appears in its minimized state.

wsMaximized	The form appears in its maximized state.


TCustomForm events

TCustomForm	Alphabetically	Legend

In TCustomForm

OnActivate

OnClose

OnCloseQuery

OnCreate

OnDeactivate

OnDestroy

OnHelp

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TCustomForm events

TCustomForm	By object	Legend

OnActivate

OnClick

OnClose

OnCloseQuery

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHelp

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TCustomForm::OnActivate

TCustomForm	See also 	Example

Occurs when the form becomes active.

__property Classes::TNotifyEvent OnActivate = {read=FOnActivate, write=FOnActivate, stored=IsForm};

Description

Use OnActivate to perform special processing when the form receives focus. A form becomes active when focus is transferred to it (when the user clicks on the form, for example).

For MDI child windows (forms with FormStyle property values of fsMDIChild), OnActivate occurs only when focus is shifted from one child to another. If focus is shifted from a non-MDI child window to an MDI child, the OnActivate event occurs for the MDI parent form.

Note:	The OnActivate event of the application (TApplication), not the form, occurs when Windows switches control from another application.


TCustomForm::OnClose

TCustomForm	See also 	Example

Occurs when the form closes.

enum TCloseAction { caNone, caHide, caFree, caMinimize };

typedef void __fastcall (__closure *TCloseEvent)(System::TObject* Sender, TCloseAction &Action);

__property TCloseEvent OnClose = {read=FOnClose, write=FOnClose, stored=IsForm};

Description

Use OnClose to perform special processing when the form closes. The OnClose event specifies which event handler to call when a form is about to close. The handler specified by OnClose might, for example, test to make sure all fields in a data-entry form have valid contents before allowing the form to close.

A form is closed by the Close method or when the user chooses Close from the form's system menu.

The TCloseEvent type points to a method that handles the closing of a form. The value of the Action parameter determines if the form actually closes. These are the possible values of Action:

Value	Meaning

caNone	The form is not allowed to close, so nothing happens.

caHide	The form is not closed, but just hidden. Your application can still access a hidden form.

caFree	The form is closed and all allocated memory for the form is freed.

caMinimize	The form is minimized, rather than closed. This is the default action for MDI child forms.

If a form is an MDI child form, and its BorderIcons property is biMinimize, then the default Action is caMinimize. If a MDI child form does not have these settings, the default Action is caNone, meaning that nothing happens when the user attempts to close the form.

If a form is an SDI child form, Action defaults to caHide.

To close and form and free it in an OnClose event, set Action to caFree.


TCustomForm::OnCloseQuery

TCustomForm	See also 	Example

Occurs when the Close method is called or when the user chooses Close from the form's System menu.

typedef void __fastcall (__closure *TCloseQueryEvent)(System::TObject* Sender, bool &CanClose);

__property TCloseQueryEvent OnCloseQuery = {read=FOnCloseQuery, write=FOnCloseQuery, stored=IsForm};

Description

Use OnCloseQuery to specify the conditions under which the form can close. An OnCloseQuery event handler contains a Boolean CanClose variable that determines whether a form is allowed to close. Its default value is true.

You can use an OnCloseQuery event handler to ask users if they are sure they really want the form closed immediately. For example, you can use the handler to display a message box that prompts the user to save a file before closing the form.

The TCloseQueryEvent type points to the method that determines whether a form can be closed. The value of the CanClose parameter determines if the form can close or not.


TCustomForm::OnCreate

TCustomForm	See also 	Example

Occurs when the form is created.

__property Classes::TNotifyEvent OnCreate = {read=FOnCreate, write=FOnCreate, stored=IsForm};

Description

Use OnCreate to perform special processing when the form is created and is invoked by TCustomForm’s constructor. Either implement this event or override the constructor of the form; do not do both. Any objects created in the OnCreate event should be freed by the OnDestroy event.

When a form is being created and its Visible property is true, the following events occur in the order listed:

1.	OnCreate

2.	OnShow

3.	OnActivate

4.	OnPaint


TCustomForm::OnDeactivate

TCustomForm	See also

Occurs when the form loses focus.

__property Classes::TNotifyEvent OnDeactivate = {read=FOnDeactivate, write=FOnDeactivate, stored=IsForm};

Description

Use OnDeactivate to perform special processing when the form transitions from being the active form to another form in the same application becoming the active form. If activation goes to another application, this event is not triggered. To determine if another application has become active, Use the TApplication object’s OnDeactivate event.


TCustomForm::OnDestroy

TCustomForm	See also 	Example

Occurs when the form is destroyed.

__property Classes::TNotifyEvent OnDestroy = {read=FOnDestroy, write=FOnDestroy, stored=IsForm};

Description

Use OnDestroy to perform special processing when the form is destroyed. Either implement this event or override the destructor of the class, but not both. This event should destroy any objects created in the OnCreate event.


TCustomForm::OnHelp

TCustomForm	See also

Occurs when the form receives a request for help.

typedef bool __fastcall (__closure *THelpEvent)(Word Command, int Data, bool &CallHelp);

__property Classes::THelpEvent OnHelp = {read=FOnHelp, write=FOnHelp};

Description

Use OnHelp to write an event handler to perform special processing when help is requested.


TCustomForm::OnHide

TCustomForm	See also 	Example

Occurs when the form is hidden (that is, when its Visible property is set to false).

__property Classes::TNotifyEvent OnHide = {read=FOnHide, write=FOnHide, stored=IsForm};

Description

Use OnHide to perform special processing when the form is hidden (that is, when the form’s Visible property is set to false).


TCustomForm::OnPaint

TCustomForm	See also 	Example

Occurs when the form is redrawn.

__property Classes::TNotifyEvent OnPaint = {read=FOnPaint, write=FOnPaint, stored=IsForm};

Description

Use OnPaint to perform special processing when the form is redrawn. Any special painting on the form should be done in this event. OnPaint occurs before any controls on the form are painted.

If you use the form’s Canvas property outside the OnPaint event, it will be erased and drawn-over by the next OnPaint event.


TCustomForm::OnResize

TCustomForm	See also 	Example

Occurs when the form is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize, stored=IsForm};

Description

Use OnResize to perform special processing when the form is resized.


TCustomForm::OnShow

TCustomForm	See also 	Example

Occurs when the form is shown (that is, when its Visible property is set to true).

__property Classes::TNotifyEvent OnShow = {read=FOnShow, write=FOnShow, stored=IsForm};

Description

Use OnShow to perform special processing when the form is shown (that is, when the form’s Visible property is set to true).


TCustomForm methods

TCustomForm	Alphabetically	Legend

In TCustomForm

~TCustomForm

TCustomForm

Activate

ActiveChanged

ChangeScale

AfterConstruction

BeforeDestruction

Close

CloseQuery

CreateParams

CreateWindowHandle

CreateWnd

Deactivate

DefaultHandler

DefineProperties

DefocusControl

DestroyWindowHandle

DoHide

DoShow

FocusControl

GetChildren

GetClientRect

GetFormImage

Hide

Loaded

Notification

Paint

PaintWindow

PaletteChanged

Print

ReadState

Release

Resize

SendCancelMode

SetChildOrder

SetFocus

SetFocusedControl

SetParent

Show

ShowModal

ValidateRename

VisibleChanging

WantChildKey

WndProc

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomForm methods

TCustomForm	By object	Legend

~TCustomForm

TCustomForm

Activate

ActiveChanged

AfterConstruction

Assign

BeforeDestruction

BeginDrag

BringToFront

Broadcast

CanFocus

ChangeScale

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

CreateParams

CreateWindowHandle

CreateWnd

Deactivate

DefaultHandler

DefineProperties

DefocusControl

DestroyComponents

Destroying

DestroyWindowHandle

DisableAlign

DisableAutoRange

Dispatch

DoHide

DoShow

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetChildren

GetClientRect

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

Loaded

MethodAddress

MethodName

NewInstance

Notification

Paint

PaintTo

PaintWindow

PaletteChanged

Perform

Print

ReadState

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

Resize

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetChildOrder

SetFocus

SetFocusedControl

SetParent

SetTextBuf

Show

ShowModal

Update

UpdateControlState

ValidateRename

VisibleChanging

WantChildKey

WndProc


TCustomForm::Activate

TCustomForm	See also

Generates an OnActivate event.

DYNAMIC void __fastcall Activate(void);

Description

The form component calls Activate in response to the CM_ACTIVATE message, sent when a form gets the focus either because of a change in active windows within an application or because of the application becoming active.

The default Activate method calls any event handler attached by the user to the OnActivate event.  Override this method to change the response to CM_ACTIVATE messages.


TCustomForm::ActiveChanged

TCustomForm	See also

Responds when the active control on the form changes.

DYNAMIC void __fastcall ActiveChanged(void);

Description

TCustomForm::ActiveChange ignores changes in the active control. Override this method in a descendant class to execute some action when the active control on the form changes.


TCustomForm::AfterConstruction

TCustomForm	See also

Generates an OnCreate event.

virtual void __fastcall AfterConstruction(void);

Description

AfterConstruction is implicitly called after any object’s construction. Do not call it explicitly in your applications. TCustomForm overrides AfterConstruction to generate an OnCreate event.


TCustomForm::BeforeDestruction

TCustomForm	See also

Generates an OnDestroy event.

virtual void __fastcall BeforeDestruction(void);

Description

BeforeDestruction is implicitly called before any object’s destruction. Do not call it explicitly in your applications. TCustomForm overrides BeforeDestruction to generate an OnDestroy event.


TCustomForm::ChangeScale

TCustomForm	See also

Repositions and resizes the form by the ratio M/D, adjusting its client area and font size as needed.

DYNAMIC void __fastcall ChangeScale(int M, int D);

Description

The ScaleBy method calls ChangeScale to perform its rescaling. TCustomForm overrides ChangeScale to rescale any scrollbars and child controls before rescaling itself.


TCustomForm::Close

TCustomForm	See also 	Example

Closes the form.

void __fastcall Close(void);

Description

Call Close to close a form.

Close calls the CloseQuery method to determine if the form can close. If CloseQuery returns false, the close operation is aborted. Otherwise, the OnClose event occurs.

Note:	When the main form of the application closes, the application terminates.


TCustomForm::CloseQuery

TCustomForm	See also

Indicates whether the form can close.

bool __fastcall CloseQuery(void);

Description

Use CloseQuery to determine whether the form can close. If the form can close, CloseQuery returns true; otherwise, CloseQuery returns false.

For an MDI parent form, CloseQuery calls the CloseQuery method on the form’s MDI children to determine the return value.


TCustomForm::TCustomForm

TCustomForm	See also

Creates and initializes a new TCustomForm object.

__fastcall virtual TCustomForm(Classes::TComponent* AOwner);

__fastcall TCustomForm(Classes::TComponent* AOwner, int Dummy);

__fastcall TCustomForm(HWND ParentWindow) : Forms::TScrollingWinControl(ParentWindow) { }

Description

Do not create instances of TCustomForm. Instead, instantiate the appropriate TCustomForm descendant.

After calling the parent class’s constructor, TCustomForm initializes:

•	the Left, Top, Width, and Height properties to 0, 0, 320, and 240, respectively.

•	the WindowState property to wsNormal, the Visible property to false, the Ctrl3d property to true, the BorderIcons property to [biSystemMenu, biMinimize, biMaximize], and the BorderStyle property to bsSizeable.

•	the ParentColor to false, the ParentFont to false.

•	the ControlStyle property to [csAcceptsControls, csCaptureMouse, csClickEvents, csSetCaption, csDoubleClicks].

•	the PixelsPerInch property to the value of the Screen::PixelsPerInch property and the PrintScale property to poProportional.

Finally, TCustomForm adds the new form to the list of forms maintained by the global instance of TScreen.

The first syntax is for creating forms in an application. Pass the application object as the AOwner parameter to indicate that it is responsible for freeing the form. Using this syntax for TCustomForm objects that are not descendants of TForm results in an exception.

The second syntax is for descendants of TCustomFOrm that are not TForm objects. The AOwner parameter is the same as for the first syntax. The second parameter, Dummy, serves only to distinguish this constructor from the first. Any value passed is ignored. Applications that use this syntax must stream in an external .DFM to bind the visual components with their classes. WriteComponentResFile and ReadComponentResFile must bracket the constructor.

The third syntax creates a form embedded in a non-VCL window. This is the syntax used by ActiveX controls.


TCustomForm::TCustomForm
TCustomForm::CreateParams

TCustomForm	See also

Initializes the window-creation parameter record when the form window is created.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it passes to CreateWindowHandle. TCustomForm overrides CreateParams to customize the way the form creates its Windows representation after calling the parent class’s method. You should never need to override this method in the context of a form class.

The TCreateParams type is a data structure holding information needed when telling Windows to create a window handle. The fields of a TCreateParams record become the parameters to a call to the CreateWindowEx API function.


TCustomForm::TCustomForm
TCustomForm::CreateWindowHandle

TCustomForm	See also

Creates a form window given a set of window-creation parameters.

virtual void __fastcall CreateWindowHandle(const Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateWindowHandle to create the form window once it has been specified in the window-creation parameters. CreateWindowHandle creates the window by calling the CreateWindowEx API function, passing parameters from the record passed in the Params parameter. CreateWindowHandle removes the CS_HREDRAW and CS_VREDRAW class styles from the window class.

The TCreateParams type is a data structure holding information needed when telling Windows to create a window handle.


TCustomForm::TCustomForm
TCustomForm::CreateWnd

TCustomForm	See also

Creates the form window.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd is called when the form is created, and whenever a change to the form requires the window to be recreated. CreateWnd first calls the parent class’s CreateWnd, and then sends the newly created window messages to request notification of Windows events, and, if the window is being recreated, reloads the form from a memory stream.


TCustomForm::Deactivate

TCustomForm	See also

Generates an OnDeactivate event.

DYNAMIC void __fastcall Deactivate(void);

Description

The form component calls Deactivate in response to the CM_DEACTIVATE message, sent when a form gets the focus either because of a change in active windows within an application or because of the application becoming active.

The default Deactivate method calls any event handler attached by the user to the OnDeactivate event.  Override this method to block the OnDeactivate event or provide additional responses to the loss of activation.


TCustomForm::DefaultHandler

TCustomForm	See also

Provides message handling for all messages that the form does not fully process.

virtual void __fastcall DefaultHandler(void *Message);

Description

Override DefaultHandler to change the default message handling for the form. This is seldom necessary because messages can be handled by creating message methods.

DefaultHandler passes any otherwise-unhandled messages to the form's window procedure by calling the CallWindowProc API function.


TCustomForm::DefineProperties

TCustomForm	See also

Designates methods for storing a form's unpublished data on a stream such as a form file.

virtual void __fastcall DefineProperties(Classes::TFiler* Filer);

Description

DefineProperties calls the parent class’s method and calls the filer object's DefineProperty method for the PixelsPerInch and TextHeight properties. TForm descendants can also specify methods that read and write data other than properties by overriding the DefineProperties method.


TCustomForm::DefocusControl

TCustomForm	See also

Removes focus from a control on the form.

void __fastcall DefocusControl(Controls::TWinControl* Control, bool Removing);

Description

Use DefocusControl to remove focus from a control on the form. This method is used internally by the VCL.

Control is the control from which to remove focus. If Control is the form’s active control, the form’s ActiveControl property is set to NULL.

Removing is a Boolean value specifying whether to set focus to the control’s parent.


TCustomForm::~TCustomForm

TCustomForm	See also

Removes the form from memory.

__fastcall virtual ~TCustomForm(void);

Description

Do not call ~TCustomForm. Instead, call Release, which posts a CM_RELEASE message to itself. The handler for CM_RELEASE calls Free, which checks that the form is not already freed, and if not, calls ~TCustomForm.

~TCustomForm performs the following tasks:

•	Calls the OnDestroy event handler for the form and for the object associated with the OleFormObject property (if that property is not NULL).

•	Frees memory associated with helper objects.

•	Calls the parent object's destructor.


TCustomForm::~TCustomForm
TCustomForm::DestroyWindowHandle

TCustomForm	See also

Destroys the window created in the CreateWindowHandle method.

virtual void __fastcall DestroyWindowHandle(void);

Description

DestroyWindowHandle is called automatically to destroy the window associated with a form before destroying the form.


TCustomForm::DoHide

TCustomForm	See also

Generates an OnHide event.

DYNAMIC void __fastcall DoHide(void);

Description

The form component calls DoHide in response to the CM_SHOWINGCHANGED message, sent when the application shows or hides the form.

The default DoHide method calls any event handler attached by the user to the OnHide event.  Override DoHide to block the OnHide event or introduce additional responses when the form is hidden.


TCustomForm::DoShow

TCustomForm	See also

Generates an OnShow event.

DYNAMIC void __fastcall DoShow(void);

Description

The form component calls DoShow in response to the CM_SHOWINGCHANGED message, sent when the application shows or hides the form.

The default DoShow method calls any event handler attached by the user to the OnShow event.  Override DoShow to block the OnShow event or introduce additional responses when the form is shown.


TCustomForm::FocusControl

TCustomForm	See also

Sets focus to a control on the form.

void __fastcall FocusControl(Controls::TWinControl* Control);

Description

Use FocusControl to set focus to a control on the form.

Control is a TWinControl object encapsulating the control upon which to set focus. FocusControl sets the ActiveControl property.


TCustomForm::GetChildren

TCustomForm	See also

Returns the "child" components of the form; that is, those components that return the form from their GetParentComponent method.

typedef void __fastcall (__closure *TGetChildProc)(TComponent* Child);

DYNAMIC void __fastcall GetChildren(Classes::TGetChildProc &Proc, Classes::TComponent* Root);

Description

GetChildren is called by the streaming system that loads and saves VCL components. By default, GetChildren returns no children.

Override GetChildren for form classes that do not use the .DFM file to manage the creation of child components. For each component contained in the form, GetChildren should call the method passed in Proc. These calls must occur in creation order, the order the child components appear in a form file.


TCustomForm::GetClientRect

TCustomForm	See also

Returns the value of the ClientRect property.

virtual Windows::TRect __fastcall GetClientRect();

Description

GetClientRect is the protected access function for the ClientRect property. Override this method to change the way the client area of the form is defined.


TCustomForm::GetFormImage

TCustomForm	See also 	Example

Returns a bitmap of the form.

Graphics::TBitmap* __fastcall GetFormImage(void);

Description

Use the GetFormImage method to obtain a bitmap of the form.


TCustomForm::Hide

TCustomForm	See also 	Example

Hides the form.

HIDESBASE void __fastcall Hide(void);

Description

Hide sets the Visible property to false.


TCustomForm::Loaded

TCustomForm	See also

Performs fix-ups when the form is first loaded into memory.

virtual void __fastcall Loaded(void);

Description

Loaded overrides the parent class’s method to give focus to the ActiveControl if it is assigned. Before assigning focus, Loaded calls the parent class’s method to perform any lower-level initialization.


TCustomForm::Notification

TCustomForm	See also

Responds to notifications that objects are about to be inserted or removed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

Notification is called when the component specified by AComponent is about to be inserted or removed, as specified by Operation. By default, forms pass along the notification to their owned components, if any. In addition, TCustomForm::Notification makes internal adjustments if the main menu is added or deleted.

A form can, if needed, override Notification to make other adjustments when components are inserted or removed. In particular, if a form has object fields or properties that contains references to other components, it might check the notifications of component removals and invalidate those references as needed.


TCustomForm::Paint

TCustomForm	See also

Generates an OnPaint event.

DYNAMIC void __fastcall Paint(void);

Description

The form component calls Paint in response to the WM_PAINT message (sent when the window needs to be painted) before rendering all controls on the form.

The default Paint method calls any event handler attached by the user to the OnPaint event.  Override Paint to block the OnPaint event or to draw additional features before or after the OnPaint event.


TCustomForm::PaintWindow

TCustomForm	See also

Repaints the contents of the form before all child controls are painted.

virtual void __fastcall PaintWindow(HDC DC);

Description

PaintWindow sets up the Canvas for painting and generates an OnPaint event at runtime or draws the designer grid at design time.  After PaintWindow has painted the form window, all child controls are painted.


TCustomForm::PaletteChanged

TCustomForm	See also

Responds to changes in the system's palette by realizing the control's palette as returned from GetPalette.

DYNAMIC bool __fastcall PaletteChanged(bool Foreground);

Description

PaletteChanged is called automatically when the system palette changes. The Foreground parameter indicates whether the palette realization should treat this control's palette as being in the foreground or the background. The return value from PaletteChanged indicates whether the form actually realized its palette, returning true only if the form has an associated palette.

Most applications should not need to alter the default behavior of PaletteChanged.


TCustomForm::Print

TCustomForm	See also	Example

Prints the form.

void __fastcall Print(void);

Description

Use the Print method to print the form


TCustomForm::ReadState

TCustomForm	See also

Reads the form's published properties, stored data, and owned components from a reader object.

virtual void __fastcall ReadState(Classes::TReader* Reader);

Description

ReadState is part of a sequence of calls used by the VCL streaming system that loads and saves VCL components.  It reads the values of all the component's published properties, stored data, and owned components from the reader object passed in Reader. Do not call ReadState directly.

Any descendent classes overriding ReadState should end with a call to the parent class’s ReadState method.


TCustomForm::Release

TCustomForm	See also	Example

Destroys the form and frees its associated memory.

void __fastcall Release(void);

Description

Use Release to destroy the form and free its associated memory.

Release does not destroy the form until all event handlers of the form and event handlers of components on the form have finished executing. Any event handlers of the form should use Release. Failing to do so could lead to an access violation.


TCustomForm::Resize

TCustomForm	See also

Generates an OnResize event.

DYNAMIC void __fastcall Resize(void);

Description

The form calls Resize in response to the WM_SIZE message, indicating a change in the size of the form.

By default, Resize does nothing except call any event handler attached to the OnResize event. Override Resize to block the OnResize event or provide other responses in addition to the parent class’s event-handler call.


TCustomForm::SendCancelMode

TCustomForm	See also

Cancels modes on the form.

HIDESBASE void __fastcall SendCancelMode(Controls::TControl* Sender);

Description

Use SendCancelMode to release the mouse capture and cancel scroll bar input and menu processing on the form.


TCustomForm::SetChildOrder

TCustomForm	See also

Changes the order in which Child appears when GetChildren is called.

DYNAMIC void __fastcall SetChildOrder(Classes::TComponent* Child, int Order);

Description

Use SetChildOrder to change the order in which child components are loaded and saved. The Child moves as if it were an item in a list object: items previously below the child's old position move up, and those below the new position move down.


TCustomForm::SetFocus

TCustomForm	See also	Example

Sets focus to the form.

virtual void __fastcall SetFocus(void);

Description

Use SetFocus to give the form input focus. SetFocus calls the SetFocus method of the active control, if one exists. To determine whether the form has focus, use the Active property.


TCustomForm::SetFocusedControl

TCustomForm	See also

Sets focus to a control on the form.

bool __fastcall SetFocusedControl(Controls::TWinControl* Control);

Description

Use SetFocusedControl to give a control on the form input focus.  SetFocusedControl returns false if the Control specified by the Control parameter was already in the process of receiving focus, true otherwise.

Note:	A return value of true does not indicate the control has successfully received input focus.  If the Control can’t have focus (for example, if it is not visible), SetFocusedControl will still return true, indicating that an attempt was made.


TCustomForm::SetParent

TCustomForm	See also

Sets the Parent property.

virtual void __fastcall SetParent(Controls::TWinControl* AParent);

Description

SetParent is the protected implementation of the Parent property. It overrides the parent class’s method to regenerate the form’s window when the Parent property is changed to NULL.


TCustomForm::Show

TCustomForm	See also	Example

Shows the form.

HIDESBASE void __fastcall Show(void);

Description

Use Show to set the form’s Visible property to true and to bring the form to the front of other forms on the screen.


TCustomForm::ShowModal

TCustomForm	See also 	Example

Shows a form as a modal dialog.

int __fastcall ShowModal(void);

Description

Use ShowModal to show a form as a modal form.  When the form is shown in a modal state, the application can’t continue to run until the form is closed.

To close a modal form, set its ModalResult property to a nonzero value.

ShowModal returns value to which the ModalResult property is set when it closes the form.


TCustomForm::ValidateRename

TCustomForm	See also

Determines if a form can rename one of its owned components.

virtual void __fastcall ValidateRename(Classes::TComponent* AComponent, const System::AnsiString CurName, const System::AnsiString NewName);

Description

The ValidateRename method checks to see if a form can rename one of its owned components, passed in AComponent, from its current name (CurName) to the string passed in NewName. If AComponent is NULL or NewName is already the name of a component in the form’s list, ValidateRename throws an EComponentError exception.


TCustomForm::VisibleChanging

TCustomForm	See also

Responds just before the form changes the value of its Visible property.

DYNAMIC void __fastcall VisibleChanging(void);

Description

If, for some reason, the form should not change its visible state, it should throw an exception.


 TCustomForm::WantChildKey

TCustomForm

Indicates whether the form processes keyboard input for a control it owns.

virtual bool __fastcall WantChildKey(Controls::TControl* Child, Messages::TMessage &Message);

Description

WantChildKey is called by any control that the form owns when the control receives keyboard input. If WantChildKey returns true, the control performs no further processing in response to the keyboard input, instead deferring to its parent form to respond to the keystroke. In its default implementation, WantChildKey always returns false; it is overridden in TActiveForm to implement certain ActiveX functionality.


TCustomForm::WndProc

TCustomForm	See also

Provides specific message responses for the form.

struct TMessage

{

  Cardinal Msg;

  union

  {

    struct

    {

      Word WParamLo;

      Word WParamHi;

      Word LParamLo;

      Word LParamHi;

      Word ResultLo;

      Word ResultHi;

    };

    struct

    {

      int WParam;

      int LParam;

      int Result;

    };

  };

};

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc is the first method that receives messages for a form. After calling the parent class’s method, WndProc performs some window activation, focus, and position message handling necessary to keep in sync with Windows. Override WndProc to change how the form responds to Windows messages.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl


TCustomGroupBox

Hierarchy	Properties	Methods	See also

TCustomGroupBox is the abstract base class for all group-box components.

Unit

stdctrls

Description

Group boxes are visual components that act as containers for sets of related controls, such as radio buttons. Group boxes may also contain other group boxes. TCustomGroupBox is the abstract class from which all group-box components—including TGroupBox, TRadioGroup, and TDBRadioGroup—descend.

In addition to the methods it inherits from TCustomControl, TCustomGroupBox overrides the AlignControls method (inherited from TWinControl) to handle positioning of components within the group box. TCustomGroupBox also overrides the Paint and Create methods.


TCustomGroupBox properties

TCustomGroupBox	Alphabetically	Legend

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomGroupBox properties

TCustomGroupBox	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomGroupBox methods

TCustomGroupBox	Alphabetically	Legend

In TCustomGroupBox

~TCustomGroupBox

Paint

TCustomGroupBox

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomGroupBox methods

TCustomGroupBox	By object	Legend

~TCustomGroupBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Paint

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomGroupBox

Update

UpdateControlState


TCustomGroupBox::TCustomGroupBox

TCustomGroupBox	See also

Creates and initializes a TCustomGroupBox instance.

__fastcall virtual TCustomGroupBox(Classes::TComponent* AOwner);

__fastcall TCustomGroupBox(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Do not instantiate a TCustomGroupBox object. To add a group box to a form, create an instance of a TCustomGroupBox descendant using the new keyword.

Pass a single component as a parameter to provide the group box with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the group box in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the group box is implemented as an ActiveX control.

After calling the parent object's constructor method, TCustomGroupBox initializes the ControlStyle property by turning on the following flags: csAcceptsControls, csCaptureMouse, csClickEvents, csSetCaption, csDoubleClicks, and csReplicatable. TCustomGroupBox also sets the Width and Height properties to 185 and 105 pixels, respectively.


TCustomGroupBox::Paint

TCustomGroupBox	See also

Renders the onscreen image of the group box.

virtual void __fastcall Paint(void);

Description

Paint creates a Windows RECT structure, draws a border around it, and calls the Windows DrawText function to fill in the caption. If Ctl3D (a protected property, inherited from TWinControl) is set to true, then Paint draws the border with a three-dimensional look.


TCustomGroupBox::~TCustomGroupBox

TCustomGroupBox

~TCustomGroupBox frees the memory associated with the TCustomGroupBox object.

__fastcall virtual ~TCustomGroupBox(void) { }

Description

Do not call ~TCustomGroupBox directly. Instead, use the delete keyword on the object, which causes ~TCustomGroupBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


TCustomGrid

Hierarchy	Properties	Methods	See also

TCustomGrid is the abstract base type for all components that present information in a two-dimensional grid.

Unit

grids

Description

Use TCustomGrid as a base class when defining components that represent information in a tabular format. TCustomGrid introduces properties and methods to control the appearance and behavior of the grid, including responses to mouse actions and user editing.

Do not create instances of TCustomGrid. Instead, put a grid control in a form by instantiating a descendant of TCustomGrid. Use TDrawGrid to represent non-textual material in a tabular grid. For text, use a TStringGrid object. If the text represents field values from a dataset, use TDBGrid.


TCustomGrid properties

TCustomGrid	Alphabetically	Legend

In TCustomGrid

BorderStyle

Col

ColCount

ColWidths

DefaultColWidth

DefaultDrawing

DefaultRowHeight

EditorMode

FixedColor

FixedCols

FixedRows

GridHeight

GridLineWidth

GridWidth

HitTest

InplaceEditor

LeftCol

Options

Row

RowCount

RowHeights

ScrollBars

Selection

TabStops

TopRow

VisibleColCount

VisibleRowCount

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomGrid properties

TCustomGrid	By object	Legend

Align

BorderStyle

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Col

ColCount

Color

ColWidths

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DefaultColWidth

DefaultDrawing

DefaultRowHeight

DesignInfo

EditorMode

Enabled

FixedColor

FixedCols

FixedRows

GridHeight

GridLineWidth

GridWidth

Handle

Height

HelpContext

Hint

HitTest

InplaceEditor

Left

LeftCol

Name

Options

Owner

Parent

ParentColor

ParentWindow

Row

RowCount

RowHeights

ScrollBars

Selection

ShowHint

Showing

TabOrder

TabStop

TabStops

Tag

Top

TopRow

VCLComObject

Visible

VisibleColCount

VisibleRowCount

Width

WindowProc


TCustomGrid::BorderStyle

TCustomGrid	See also

Determines whether a single line border is drawn around the grid.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Set BorderStyle to bsSingle to add a single line border around the grid’s image. Set BorderStyle to bsNone to omit the border.

The visual effect of BorderStyle is influenced by the value of the Ctrl3D property. Experiment with different combinations of BorderStyle and Ctrl3D to achieve the desired look.


TCustomGrid.Col
TCustomGrid::Col

TCustomGrid	See also 	Example

Specifies the index of the column that contains the selected cell.

__property int Col = {read=FCurrent.X, write=SetCol, nodefault};

Description

Use Col at runtime to determine the current column in the grid. Setting Col moves focus to the cell in the current row that is in the new column. The first column has an index of 0, the second column an index of 1, and so on.

The selected cell in the grid can be located by reading the Col property and the Row property to obtain the indexes of its column and row. When focus moves to the grid, the selected cell gets input focus.


TCustomGrid::ColCount

TCustomGrid	See also 	Example

Specifies the number of columns in the grid.

__property int ColCount = {read=FColCount, write=SetColCount, default=5};

Description

Read ColCount to determine the number entries in the ColWidths array. Set ColCount to add or delete columns at the righthand side of the grid. The value of ColCount includes any fixed columns at the left of the grid as well as the scrollable columns in the body of the grid.


TCustomGrid::ColWidths

TCustomGrid	See also	Example

Indicates the width (in pixels) of all the columns in the grid.

__property int ColWidths[int Index] = {read=GetColWidths, write=SetColWidths};

Description

Read ColWidths to determine the width of the cells in the column specified by the Index parameter. An index of 0 refers to the first column. Set ColWidths at runtime to change the width of an individual column.

If the width of a column has not been set explicitly by resizing with the mouse, or by using the ColWidths property, its width is DefaultColWidth.

Use the ColCount property to determine the number of entries in the ColWidths array.


TCustomGrid::DefaultColWidth

TCustomGrid	See also	Example

Determines the width (in pixels) of all columns that have not been explicitly resized.

__property int DefaultColWidth = {read=FDefaultColWidth, write=SetDefaultColWidth, default=64};

Description

Set DefaultColWidth to change the size of all columns in the grid. When DefaultColWidth is set, columns that have been resized using the mouse or by setting the ColWidths property are given the DefaultColWidth as well.

When new columns are added to the grid using the ColCount property, they are created with a width of DefaultColWidth.


TCustomGrid::DefaultDrawing

TCustomGrid	See also	Example

Determines whether the Cells are painted when the grid is drawn.

__property bool DefaultDrawing = {read=FDefaultDrawing, write=FDefaultDrawing, default=1};

Description

Set DefaultDrawing to true to have the grid automatically paint the cells in the grid, including adding the background color, the 3-D effects on the fixed cells, and the focus rectangle around the selected cell. Set DefaultDrawing to false to skip the painting of the cells when the grid is drawn.

When DefaultDrawing is false, the cells should be painted using the DrawCell method. For TCustomGrid, DrawCell is an abstract method. Descendants of TCustomGrid use DrawCell to provide their own customized drawing code, or to generate an OnDrawCell event.


TCustomGrid::DefaultRowHeight

TCustomGrid	See also	Example

Specifies the height (in pixels) of all rows that have not been explicitly resized.

__property int DefaultRowHeight = {read=FDefaultRowHeight, write=SetDefaultRowHeight, default=24};

Description

Set DefaultRowHeight to change the size of all rows in the grid. When DefaultRowHeight is set, rows that have been resized using the mouse or by setting the RowHeights property are given the DefaultRowHeight as well.

When new rows are added to the grid using the RowCount property, they are created with a height of DefaultRowHeight.


TCustomGrid::EditorMode

TCustomGrid	See also

Determines whether the current cell can be edited.

__property bool EditorMode = {read=FEditorMode, write=SetEditorMode, nodefault};

Description

Set EditorMode to true, at runtime, to put the grid in edit mode. When EditorMode is true, the user can edit cells in the grid. When the user presses F2, EditorMode is set to true. When the user presses Enter, the value of EditorMode is toggled.

Note:	EditorMode has no effect if the Options property does not include goEditing or if the Options property includes goAlwaysShowEditor.


TCustomGrid::FixedColor

TCustomGrid	See also	Example

Specifies the background color of the fixed rows and columns in the grid.

__property Graphics::TColor FixedColor = {read=FFixedColor, write=SetFixedColor, default=-2147483633};

Description

Set FixedColor to specify the color for the nonscrolling cells in the grid. The scrolling region of the grid is drawn using the Color property.


TCustomGrid::FixedCols

TCustomGrid	See also	Example

Specifies the number of columns on the left of the grid that cannot be scrolled.

__property int FixedCols = {read=FFixedCols, write=SetFixedCols, default=1};

Description

Set FixedCols to create or get rid of nonscrolling columns. Nonscrolling columns appear at the left of the grid, and are always visible, even when the user scrolls the other columns in the grid. Use nonscrolling columns for displaying row titles or row numbers, or to implement a scroll lock that the user can set.

Nonscrolling columns are visually distinct from the scrollable columns in the grid. They are painted with a separate background color, and their cells have a raised, 3-D look when the Ctrl3D property is true.

Note:	Grids must include at least one scrolling column. Do not set FixedCols to a value greater than ColCount - 1.


TCustomGrid::FixedRows

TCustomGrid	See also	Example

Specifies the number of rows on the left of the grid that cannot be scrolled.

__property int FixedRows = {read=FFixedRows, write=SetFixedRows, default=1};

Description

Set FixedRows to create or get rid of nonscrolling rows. Nonscrolling rows appear at the top of the grid, and are always visible, even when the user scrolls the other rows in the grid. Use nonscrolling rows for displaying column titles or column numbers.

Nonscrolling rows are visually distinct from the scrollable rows in the grid. They are painted with a separate background color, and their cells have a raised, 3-D look when the Ctrl3D property is true.

Note:	Grids must include at least one scrolling row. Do not set FixedRows to a value greater than RowCount - 1.


TCustomGrid::GridHeight

TCustomGrid	See also

Specifies the height of the grid in pixels.

__property int GridHeight = {read=GetGridHeight, nodefault};

Description

Read GridHeight to determine the size of the grid. If GridHeight is less than the value of ClientHeight, all of the rows of the grid appear in the control with an empty region below the grid. If the underlying grid is too tall to appear in the control, GridHeight is the same as ClientHeight, and the user must scroll to see the entire contents of the grid.


TCustomGrid::GridLineWidth

TCustomGrid	See also	Example

Specifies the width (in pixels) of the lines that separate the cells of the grid.

__property int GridLineWidth = {read=FGridLineWidth, write=SetGridLineWidth, default=1};

Description

Set GridLineWidth to make the lines that separate the cells in the grid heavier or lighter. When GridLineWidth is zero, no separators are drawn between the cells of the grid.

GridLineWidth will have no effect if the Options property does not include goFixedHorzLine, goFixedVertLine, goHorzLine, or goVertLine.

Note:	Even when GridLineWidth is zero, the cells in the fixed rows and columns of the grid will appear distinct if the Ctrl3D property is true. Set Ctrl3D to false to remove the raised effect that separates the cells in the fixed region of the grid.

Note:	Values greater than 3 pixels are not recommended for applications that will run on Windows 95 because of distortions that can appear.


TCustomGrid::GridWidth

TCustomGrid	See also	Example

Specifies the width of the grid in pixels.

__property int GridWidth = {read=GetGridWidth, nodefault};

Description

Read GridWidth to determine the size of the grid. If GridWidth is less than the value of ClientWidth, all of the columns of the grid appear in the control with an empty region to the right of the grid. If the underlying grid is too wide to appear in the control, GridWidth is the same as ClientWidth, and the user must scroll to see the entire contents of the grid.


TCustomGrid::HitTest

TCustomGrid	See also

Indicates the current position of the mouse cursor.

__property tagPOINT HitTest = {read=FHitTest};

Description

Read HitTest to determine the position of the mouse when it is over the grid or when the grid has captured the mouse. HitTest may represent a position that is not within the client area of the grid control if the user is moving or resizing the rows or columns, or if the user is selecting a range of cells using the mouse. HitTest is the position of the mouse cursor in the coordinate system where (0,0) is the upper left corner of the grid control’s client area.


TCustomGrid::InplaceEditor

TCustomGrid	See also

Designates the edit control the grid uses to allow users to edit the contents of the selected cell.

__property TInplaceEdit* InplaceEditor = {read=FInplaceEdit};

Description

Read InplaceEditor to gain direct access to the edit control that sits on top of the selected cell when the grid is in edit mode. The inplace editor is created the first time the grid is put in edit mode. It is not destroyed until the grid is destroyed. The grid moves the editor when the selected cell changes. The grid hides the editor’s window when the grid goes out of edit mode.


TCustomGrid::LeftCol

TCustomGrid	See also	Example

Specifies the index of the first visible scrollable column in the grid.

__property int LeftCol = {read=FTopLeft.X, write=SetLeftCol, nodefault};

Description

Read LeftCol to determine the index of the first column in the scrollable region that is visible. Set LeftCol to scroll the columns in the grid so that the column with index LeftCol is the first column after the fixed columns.


TCustomGrid::Options

TCustomGrid 	See also

Specifies various display and behavioral properties of the grid.

enum TGridOption { goFixedVertLine, goFixedHorzLine, goVertLine, goHorzLine, goRangeSelect, goDrawFocusSelected, goRowSizing, goColSizing, goRowMoving, goColMoving, goEditing, goTabs, goRowSelect, goAlwaysShowEditor, goThumbTracking };

typedef Set<TGridOption, goFixedVertLine, goThumbTracking>  TGridOptions;

__property TGridOptions Options = {read=FOptions, write=SetOptions, default=31};

Description

Set Options to include the desired properties for the grid. Options is a set drawn from the following values:

Value	Meaning

goFixedVertLine	Vertical lines are drawn to separate the fixed (nonscrolling) columns in the grid.

goFixedHorzLine	Horizontal lines are drawn to separate the fixed (nonscrolling) rows in the grid.

goVertLine	Vertical lines are drawn to separate the scrollable columns in the grid.

goHorzLine	Horizontal lines are drawn to separate the scrollable rows in the grid.

goRangeSelect	Users can select ranges of cells at one time. goRangeSelect is ignored if Options includes goEditing.

goDrawFocusSelected	Cells with input focus are drawn the with a special highlight color, just like selected cells without input focus. If goDrawFocusSelected is not included, the cell with input focus is distinguished by a focus rectangle, not by a special background color.

goRowSizing	Scrollable rows can be individually resized.

goColSizing	Scrollable columns can be individually resized.

goRowMoving	Scrollable rows can be moved using the mouse.

goColMoving	Scrollable columns can be moved using the mouse.

goEditing	Users can edit the contents of cells. When goEditing is included in Options, goRangeSelect has no effect.

goTabs	Users can navigate through the cells in the grid using Tab and Shift+Tab.

goRowSelect	Entire rows are selected rather than individual cells. If goRowSelect is included in Options, goAlwaysShowEditor has no effect.

goAlwaysShowEditor	The grid is locked into edit mode. The user does not need to use Enter or F2 to turn on EditorMode. If Options does not include goEditing, goAlwaysShowEditor has no effect. If Options includes goRowSelect, goAlwaysShowEditor has no effect.

goThumbTracking	The grid image updates while the user is dragging the thumb of the scrollbar. If goThumbTracking is not included, the image does not update until the user releases the thumb in a new position.


TCustomGrid.Row
TCustomGrid::Row

TCustomGrid	See also 	Example

Specifies the index of the row that contains the selected cell.

__property int Row = {read=FCurrent.Y, write=SetRow, nodefault};

Description

Use Row at runtime to determine the current row in the grid. Setting Row moves focus to the cell in the current column that is in the new row. The first row has an index of 0, the second row an index of 1, and so on.

The selected cell in the grid can be located by reading the Row property and the Col property to obtain the indexes of its row and column. When focus moves to the grid, the selected cell gets input focus.


TCustomGrid::RowCount

TCustomGrid	See also 	Example

Specifies the number of rows in the grid.

__property int RowCount = {read=FRowCount, write=SetRowCount, default=5};

Description

Read RowCount to determine the number entries in the RowHeights array. Set RowCount to add or delete rows at the bottom of the grid. The value of RowCount includes any fixed rows at the top of the grid as well as the scrollable rows in the body of the grid.


TCustomGrid::RowHeights

TCustomGrid	See also 	Example

Gives the height (in pixels) of all rows in the grid.

__property int RowHeights[int Index] = {read=GetRowHeights, write=SetRowHeights};

Description

Read RowHeights to determine the height of the cells in the row specified by the Index parameter. An index of 0 refers to the first row. Set RowWidths at runtime to change the height of an individual row.

If the height of a row has not been set explicitly by resizing with the mouse, or by using the RowHeights property, it’s height is DefaultRowHeight.

Use the RowCount property to determine the number of entries in the RowHeights array.


TCustomGrid::ScrollBars

TCustomGrid	See also

Specifies whether the grid includes horizontal and vertical scroll bars.

enum TScrollStyle { ssNone, ssHorizontal, ssVertical, ssBoth };

__property Stdctrls::TScrollStyle ScrollBars = {read=FScrollBars, write=SetScrollBars, default=3};

Description

Use ScrollBars to give the grid horizontal or vertical scroll bars. ScrollBars can take one of the following values:

Value	Meaning

ssNone	The grid has no scroll bars.

ssHorizontal	The grid has a single scroll bar on the bottom edge.

ssVertical	The grid has a single scroll bar on the right edge.

ssBoth	The grid has a scroll bar on both the bottom and right edges.

Note:	If all the cells in the grid fit in the ClientWidth, no horizontal scrollbar appears, even if ScrollBars is ssHorizontal or ssBoth. If all the cells fit in the ClientHeight, no vertical scrollbar appears, even if ScrollBars is ssVertical or ssBoth.


TCustomGrid::Selection

TCustomGrid	See also	Example

Indicates the boundaries of the current selection.

struct TGridCoord

{

  int X;

  int Y;

};

struct TGridRect

{

  union

  {

    struct

    {

      TGridCoord TopLeft;

      TGridCoord BottomRight;

    };

    struct

    {

      int Left;

      int Top;

      int Right;

      int Bottom;

    };

  };

};

__property TGridRect Selection = {read=GetSelection, write=SetSelection};

Description

Set Selection to select a range of cells in the grid. Selection can either represent the first column, first row, last column and last row in the grid, or the row and column coordinates of the upper left and bottom right cells in the selected region.

Selection can only indicate more than one cell when Options includes goRangeSelect.


TCustomGrid::TabStops

TCustomGrid	See also

Indicates whether the user can tab to specified columns in the grid.

__property bool TabStops[int Index] = {read=GetTabStops, write=SetTabStops};

Description

Set TabStops to false to remove the column identified by Index from the tab order. The first column in the grid is identified by an Index of 0.

Note:	When the Options property does not include goTabs, the user can’t tab to any column, even if TabStops is true.


TCustomGrid::TopRow

TCustomGrid	See also	Example

Specifies the index of the first visible scrollable row in the grid.

__property int TopRow = {read=FTopLeft.Y, write=SetTopRow, nodefault};

Description

Read TopRow to determine the index of the first row in the scrollable region that is visible. Set TopRow to scroll the rows in the grid so that the row with index TopRow is the first row after the fixed rows.


TCustomGrid::VisibleColCount

TCustomGrid	See also	Example

Indicates the number of scrollable columns visible in the grid.

__property int VisibleColCount = {read=GetVisibleColCount, nodefault};

Description

Use VisibleColCount to determine the number of scrollable columns fully visible in the grid. VisibleColCount does not include the fixed columns counted by the FixedCols property. It does not include any partially visible columns on the right edge of the grid.


TCustomGrid::VisibleRowCount

TCustomGrid	See also	Example

Indicates the number of scrollable rows visible in the grid.

__property int VisibleRowCount = {read=GetVisibleRowCount, nodefault};

Description

Use VisibleRowCount to determine the number of scrollable rows fully visible in the grid. VisibleRowCount does not include the fixed rows counted by the FixedRows property. It does not include any partially visible rows on the bottom of the grid.


TCustomGrid methods

TCustomGrid	Alphabetically	Legend

In TCustomGrid

~TCustomGrid

AdjustSize

BoxRect

CanEditAcceptKey

CanEditModify

CanEditShow

CanGridAcceptKey

CellRect

ColumnMoved

ColWidthsChanged

CreateEditor

CreateParams

DefineProperties

DeleteColumn

DeleteRow

DoExit

DrawCell

GetEditLimit

GetEditMask

GetEditText

GetGridHeight

GetGridWidth

HideEditor

InvalidateCell

InvalidateCol

InvalidateEditor

InvalidateRow

KeyDown

KeyPress

MouseCoord

MouseDown

MouseMove

MouseUp

MoveColRow

MoveColumn

MoveRow

Paint

RowHeightsChanged

RowMoved

ScrollData

SelectCell

SetEditText

ShowEditor

ShowEditorChar

SizeChanged

Sizing

TCustomGrid

TimedScroll

TopLeftChanged

UpdateDesigner

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomGrid methods

TCustomGrid	By object	Legend

~TCustomGrid

AdjustSize

Assign

BeginDrag

BoxRect

BringToFront

Broadcast

CanEditAcceptKey

CanEditModify

CanEditShow

CanFocus

CanGridAcceptKey

CellRect

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ColumnMoved

ColWidthsChanged

ContainsControl

ControlAtPos

CreateEditor

CreateParams

DefaultHandler

DefineProperties

DeleteColumn

DeleteRow

DestroyComponents

Destroying

DisableAlign

Dispatch

DoExit

DragDrop

Dragging

DrawCell

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetEditLimit

GetEditMask

GetEditText

GetGridHeight

GetGridWidth

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

HideEditor

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

InvalidateCell

InvalidateCol

InvalidateEditor

InvalidateRow

KeyDown

KeyPress

MethodAddress

MethodName

MouseCoord

MouseDown

MouseMove

MouseUp

MoveColRow

MoveColumn

MoveRow

NewInstance

Paint

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

RowHeightsChanged

RowMoved

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollData

SelectCell

SendToBack

SetBounds

SetEditText

SetFocus

SetTextBuf

Show

ShowEditor

ShowEditorChar

SizeChanged

Sizing

TCustomGrid

TimedScroll

TopLeftChanged

Update

UpdateControlState

UpdateDesigner


TCustomGrid::AdjustSize

TCustomGrid	See also

Adds or deletes rows or columns from the grid.

DYNAMIC void __fastcall AdjustSize(int Index, int Amount, bool Rows);

Description

Grid components call AdjustSize internally to fix up the number of rows or columns when the user resizes them using the mouse. Index is the index of the row or column where the insertion or deletion should begin. Amount is the number of rows or columns to insert (Amount > 0) or delete (Amount < 0). Rows is a boolean that indicates whether the rows or the columns are changing.


TCustomGrid::BoxRect

TCustomGrid	See also

Returns the screen coordinates of a specified set of cells.

Windows::TRect __fastcall BoxRect(int ALeft, int ATop, int ARight, int ABottom);

Description

Call BoxRect to obtain the screen coordinates, in pixels, of the cells that run from the column with index ALeft to the column with index ARight and the row with index ATop to the row with index ABottom. The coordinates of cells that are not visible onscreen are not included in the final rectangle.


TCustomGrid::CanEditAcceptKey

TCustomGrid	See also

Indicates whether the Key parameter can be entered into the current cell.

DYNAMIC bool __fastcall CanEditAcceptKey(char Key);

Description

CanEditAcceptKey provides a simple screening of keyboard input while the user is editing the contents of a cell. The CanEditAcceptKey method for TCustomGrid always returns true. Descendants of TCustomGrid override this method to screen out illegal characters.

More refined validation can be obtained by using an edit mask.


TCustomGrid::CanEditModify

TCustomGrid	See also

Indicates whether the current cell in the grid can be edited.

DYNAMIC bool __fastcall CanEditModify(void);

Description

Grid components use CanEditModify internally to determine whether to allow the user to edit the current cell. CanEditModify returns true unless the inplace editor has disallowed editing for the cell.


TCustomGrid::CanEditShow

TCustomGrid	See also

Indicates whether the inplace edit control can be created to allow editing.

virtual bool __fastcall CanEditShow(void);

Description

Grid controls call CanEditShow internally before creating the editor for a cell. CanEditShow is called after the grid has determined that the field can be edited by calling CanEditModify.

CanEditShow returns false if the Options property does not indicate that the grid allows editing, or if it indicates that the grid permits row selection. Otherwise, if the Options property indicates that the grid is locked in edit mode, or if the grid has input focus, CanEditShow returns true. If the grid is not locked in edit mode and the grid does not have input focus, CanEditShow returns false.


TCustomGrid::CanGridAcceptKey

TCustomGrid	See also

Indicates whether the grid should respond to a given key combination.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC bool __fastcall CanGridAcceptKey(Word Key, Classes::TShiftState Shift);

Description

Grid controls call CanGridAcceptKey internally to screen key combinations when the user first presses a key. The CanGridAcceptKey method for TCustomGrid always returns true. Descendants of TCustomGrid override this method to screen out irrelevant key combinations, or key combinations that indicate actions which would violate the Options or mode of the grid.


TCustomGrid::CellRect

TCustomGrid	See also

Returns the screen coordinates of a cell in the grid.

Windows::TRect __fastcall CellRect(int ACol, int ARow);

Description

Call CellRect to obtain the boundaries, in pixels, of the cell in the column and row indicated by the ACol and ARow parameters. The top left cell is specified when ACol and ARow are set to zero.

If the indicated cell is not visible, CellRect returns an empty rectangle.


TCustomGrid::ColumnMoved

TCustomGrid	See also

Provides the interface for a method that responds when the position of a column changes.

DYNAMIC void __fastcall ColumnMoved(int FromIndex, int ToIndex);

Description

ColumnMoved is called immediately after a column in the grid has moved. The FromIndex parameter is the old index of the column, and the ToIndex parameter is the new index. The ColumnMoved method of TCustomGrid does nothing. Descendants of TCustomGrid override this method to make internal adjustments or to generate an OnColumnMoved event.


TCustomGrid::ColWidthsChanged

TCustomGrid	See also

Responds when the column widths change.

DYNAMIC void __fastcall ColWidthsChanged(void);

Description

ColWidthsChanged is called immediately after the column widths change. The change can result from setting the ColWidths property, from setting the DefaultColWidth property, from moving one of the columns, or from resizing the columns with the mouse.

ColWidthsChanged adjusts the scroll bar and the position of the inplace editor to take into account the new column size and positions of the columns.


TCustomGrid::TCustomGrid

TCustomGrid	See also

Creates an instance of TCustomGrid.

__fastcall virtual TCustomGrid(Classes::TComponent* AOwner);

__fastcall TCustomGrid(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Do not directly create instances of TCustomGrid. TCustomGrid is an abstract base class for grid controls. Instead, create a descendant of TCustomGrid to create a grid control at runtime. Grid controls placed on a form at design time are created automatically.

Pass a single Component as a parameter to provide the grid with an Owner that is responsible for freeing the grid. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the grid in a non-VCL window. This syntax is used when the grid is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TCustomGrid initializes

•	BorderStyle property to bsSingle.

•	ColCount and RowCount to 5.

•	Color to clWindow and FixedColor to clBtnFace.

•	ControlStyle to [csCaptureMouse, csOpaque, csDoubleClicks, csFramed]

•	DefaultColWidth to 64 and DefaultRowHeight to 24.

•	DefaultDrawing to true.

•	EditorMode to false.

•	FixedCols and FixedRows to 1.

•	GridLineWidth to 1.

•	Options to include goFixedVertLine, goFixedHorzLine, goVertLine, goHorzLine, and goRangeSelect

•	ParentColor to false.

•	ScrollBars to ssBoth.

•	TabStop to true.


TCustomGrid::TCustomGrid
TCustomGrid::CreateEditor

TCustomGrid	See also

Creates the inplace editor control.

virtual TInplaceEdit* __fastcall CreateEditor(void);

Description

Grid controls call CreateEditor internally the first time the grid goes into edit mode. CreateEditor is exposed as a protected method so that descendants of TCustomGrid can substitute a specialized descendant of TInplaceEdit to handle cell editing.


TCustomGrid::TCustomGrid
TCustomGrid::CreateParams

TCustomGrid	See also

Initializes the window-creation parameter record.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method is called internally to specify the properties of the window that implements this control. These properties are set in the window-creation parameter record passed as Params. The fields of this record become the parameters to a call to the CreateWindowEx API function.

After calling the inherited method, CreateParams adjusts the value of Params to request that the grid receive double click messages, and to implement the values of the Ctrl3D, ScrollBars, and BorderStyle properties.


TCustomGrid::DefineProperties

TCustomGrid	See also

Adds the ColWidths and RowHeights properties to the values saved with the grid.

virtual void __fastcall DefineProperties(Classes::TFiler* Filer);

Description

DefineProperties overrides the inherited method to save the ColWidths and RowHeights properties with the grid when they contain values other than the default widths and heights.


TCustomGrid::DeleteColumn

TCustomGrid	See also

Deletes a specified column from the grid.

void __fastcall DeleteColumn(int ACol);

Description

Call DeleteColumn to remove a column from the middle of the grid. Provide the index of the column to remove as ACol. To remove the last column from the grid, set the ColCount property instead.


TCustomGrid::DeleteRow

TCustomGrid	See also

Deletes a specified from the grid.

void __fastcall DeleteRow(int ARow);

Description

Call DeleteRow to remove a row from the middle of the grid. Provide the index of the row to remove as ARow. To remove the last row from the grid, set the RowCount property instead.


TCustomGrid::~TCustomGrid

TCustomGrid	See also

Destroys an instance of TCustomGrid.

__fastcall virtual ~TCustomGrid(void);

Description

Do not call ~TCustomGrid directly in an application. Instead, use the delete keyword.


TCustomGrid::DoExit

TCustomGrid	See also

Hides the inplace editor when selection moves to another control in a form.

DYNAMIC void __fastcall DoExit(void);

Description

After calling the inherited method, which generates an OnExit event, DoExit hides the inplace editor unless the Options property includes goAlwaysShowEditor.


TCustomGrid::DrawCell

TCustomGrid	See also

Provides the prototype for a method that draws the contents of a cell in the grid.

virtual void __fastcall DrawCell(int ACol, int ARow, const Windows::TRect &ARect, TGridDrawState AState) = 0;

Description

Descendants of TCustomGrid implement the DrawCell method to draw the contents of the cell or to generate an OnDrawCell event. If the DefaultDrawing property is true, the background of the cell is painted before DrawCell is called, and the 3D effects of the fixed cells or the focus rectangle around the focused cell are drawn after DrawCell.

The ACol and ARow parameters give the column and row indexes of the cell that should be drawn. The ARect parameter gives the boundaries of the cell in the coordinates of the canvas. The AState parameter indicates whether the cell is selected, whether the cell has input focus, and whether the cell is in the fixed, non-scrolling portion of the grid.


TCustomGrid::GetEditLimit

TCustomGrid	See also

Provides the interface for a method that limits the number of characters the user can type into cells.

DYNAMIC int __fastcall GetEditLimit(void);

Description

GetEditLimit is called by the inplace editor to determine if a limit should be placed on the number of characters a user can type into a cell. GetEditLimit sets no limits. Descendants of TCustomGrid override this method to limit the text for certain cells.


TCustomGrid::GetEditMask

TCustomGrid	See also

Provides the interface for a method that returns an input mask for the specified cell.

DYNAMIC System::AnsiString __fastcall GetEditMask(int ACol, int ARow);

Description

The inplace editor calls GetEditMask to obtain any input mask associated with the cell specified by the ACol and ARow parameters. GetEditMask returns an empty string, indicating that the cell has no input mask. Descendants of TCustomGrid override this method to provide an input mask or generate an OnGetEditMask event.


TCustomGrid::GetEditText

TCustomGrid	See also

Returns the value of the indicated cell formatted for editing.

DYNAMIC System::AnsiString __fastcall GetEditText(int ACol, int ARow);

Description

The inplace editor calls GetEditText to obtain the text for the indicated cell. GetEditText returns an empty string. Descendants of TCustomGrid override the GetEditText method to return a string that represents the contents of the cell indicated by the ACol and ARow parameters.


TCustomGrid::GetGridHeight

TCustomGrid	See also

Returns the value of the GridHeight property.

int __fastcall GetGridHeight(void);

Description

GetGridHeight is the protected property access method for the GridHeight property. It computes the value of the GridHeight property based on the row heights, separator width, and the size of the control.


TCustomGrid::GetGridWidth

TCustomGrid	See also

Returns the value of the GridWidth property.

int __fastcall GetGridWidth(void);

Description

GetGridWidth is the protected property access method for the GridWidth property. It computes the value of the GridWidth property based on the column widths, separator width, and the size of the control.


TCustomGrid::HideEditor

TCustomGrid	See also

Hides the inplace editor when it is not in use.

void __fastcall HideEditor(void);

Description

Grid controls call HideEditor when the grid goes out of edit mode. HideEditor hides the window of the inplace editor.


TCustomGrid::InvalidateCell

TCustomGrid	See also

Invalidates the region occupied by a cell so that it will be repainted with the next Windows paint message.

void __fastcall InvalidateCell(int ACol, int ARow);

Description

Call InvalidateCell when the contents of a cell change so that the cell will need to be repainted. The ACol parameter is the column index of the cell, and the ARow parameter is the row index.


TCustomGrid::InvalidateCol

TCustomGrid	See also

Invalidates the region occupied by a column so that it will be repainted with the next Windows paint message.

void __fastcall InvalidateCol(int ACol);

Description

Call InvalidateCol when a column changes so that the area it occupies will need to be repainted. The ACol parameter is the column index.


TCustomGrid::InvalidateEditor

TCustomGrid	See also

Causes the inplace editor to repaint itself, moving to a new location if necessary.

void __fastcall InvalidateEditor(void);

Description

InvalidateEditor is called when the selected cell changes while the grid is in edit mode.


TCustomGrid::InvalidateRow

TCustomGrid	See also

Invalidates the region occupied by a row so that it will be repainted with the next Windows paint message.

void __fastcall InvalidateRow(int ARow);

Description

Call InvalidateRow when a row changes so that the area it occupies will need to be repainted. The ARow parameter is the row index.


TCustomGrid::KeyDown

TCustomGrid	See also

Provides special processing when the user presses a key.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

After generating an OnKeyDown event, KeyDown calls CanGridAcceptKey to screen out problematic key combinations. KeyDown moves to the appropriate cell in response to navigational key combinations, or sets the EditorMode property to true when the user presses F2.


TCustomGrid::KeyPress

TCustomGrid	See also

Provides special processing when the user presses a key.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

After generating an OnKeyPress event, KeyPress toggles the EditorMode property when the user presses the Enter key. KeyPress is called after the KeyDown method, but before the user releases the key.


TCustomGrid::MouseCoord

TCustomGrid	See also

Returns the row and column indexes of the cell that contains a point specified in screen coordinates.

struct TGridCoord

{

  int X;

  int Y;

};

TGridCoord __fastcall MouseCoord(int X, int Y);

Description

Call MouseCoord to locate the column and row of the cell which contains a given screen coordinate. Usually, MouseCoord is used to locate the cell which is under the mouse.


TCustomGrid::MouseDown

TCustomGrid	See also

Provides special processing when the user presses a mouse button.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseDown(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

MouseDown hides the editor window so that it can move selection to the cell that receives the mouse click. If the mouse lands in the hot region for beginning a move or resize of a row or column, MouseDown starts the move or resize, and provides visual feedback by changing the cursor. If the editor window was hidden, it is brought back up in its new location. Finally, MouseDown generates an OnMouseDown event.


TCustomGrid::MouseMove

TCustomGrid	See also

Provides special processing when the user moves the mouse.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseMove(Classes::TShiftState Shift, int X, int Y);

Description

If the grid is in the middle of moving or resizing a row or column, or in the middle of selecting a range of cells using the mouse, MouseMove calculates the changes implied by the mouse move and provides visual feedback to the user. Finally, MouseMove generates an OnMouseMove event.


TCustomGrid::MouseUp

TCustomGrid	See also

Provides special processing when the user releases the mouse button.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseUp(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

MouseUp finishes a move or resize operation on a row or column, or if the user is selecting a range of cells using the mouse, MouseUp finishes the select operation. Finally, MouseUp generates an OnMouseUp event.


TCustomGrid::MoveColRow

TCustomGrid	See also

Selects the cell indicated by the ACol and ARow parameters.

void __fastcall MoveColRow(int ACol, int ARow, bool MoveAnchor, bool Show);

Description

Grid controls call MoveColRow internally when changing the selected cell or cells. MoveColRow selects the indicated cell, but does not take care of removing any previous selection.

The ACol and ARow parameters are the column index and the row index of the cell to be selected. The MoveAnchor parameter indicates whether the new cell becomes the upper left corner of the selected region. MoveAnchor is true unless MoveColRow is called when extending a multicell selected region. The Show parameter indicates whether MoveColRow should ensure that the newly selected cell is visible.


TCustomGrid::MoveColumn

TCustomGrid	See also

Moves a column to a new position.

void __fastcall MoveColumn(int FromIndex, int ToIndex);

Description

Call MoveColumn to move the column identified by the FromIndex parameter to the position specified by the ToIndex parameter.


TCustomGrid::MoveRow

TCustomGrid	See also

Moves a row to a new position.

void __fastcall MoveRow(int FromIndex, int ToIndex);

Description

Call MoveRow to move the row identified by the FromIndex parameter to the position specified by the ToIndex parameter.


TCustomGrid::Paint

TCustomGrid	See also

Draws the image of the grid control on the screen.

virtual void __fastcall Paint(void);

Description

Paint is called when the grid receives a Windows paint message. Paint draws the grid, calling the DrawCell method when it is time to paint the contents of each cell. If DefaultDrawing is false, Paint does not draw the background of the cells, provide the raised 3D effects on the fixed cells, or draw the focus rectangle around the selected cell when it has focus.


TCustomGrid::RowHeightsChanged

TCustomGrid	See also

Responds when the row heights change.

DYNAMIC void __fastcall RowHeightsChanged(void);

Description

RowHeightsChanged is called immediately after the row heights change. The change can result from setting the RowHeights property, from setting the DefaultRowHeight property, from moving one of the rows, or from resizing the rows with the mouse.

RowHeightsChanged adjusts the scroll bar and the position of the inplace editor to take into account the new row size and positions of the rows.


TCustomGrid::RowMoved

TCustomGrid	See also

Provides the interface for a method that responds when the position of a row changes.

DYNAMIC void __fastcall RowMoved(int FromIndex, int ToIndex);

Description

RowMoved is called immediately after a row in the grid changes position. The FromIndex parameter is the old index of the row, and the ToIndex parameter is the new index. The RowMoved method of TCustomGrid does nothing. Descendants of TCustomGrid override this method to make internal adjustments or to generate an OnRowMoved event.


TCustomGrid::ScrollData

TCustomGrid	See also

Scrolls the visual image of the cells in the grid.

void __fastcall ScrollData(int DX, int DY);

Description

Grid controls call ScrollData internally when the nonfixed rows or columns scroll. ScrollData updates the image of the grid.


TCustomGrid::SelectCell

TCustomGrid	See also

Determines whether a particular cell in the grid can be selected.

virtual bool __fastcall SelectCell(int ACol, int ARow);

Description

Grid controls call SelectCell internally before attempting to move selection to a the cell identified by the ACol and ARow parameters. ACol and ARow are the column and row indexes for the cell, where the first column has index 0, and the top row has index 0.

The SelectCell method for TCustomGrid always returns true, allowing the cell to be selected. Descendants of TCustomGrid override this method to check the properties of the information displayed in the cell or generating an OnSelectCell event.


TCustomGrid::SetEditText

TCustomGrid	See also

Provides the interface for a method that updates the text associated with a cell.

DYNAMIC void __fastcall SetEditText(int ACol, int ARow, const System::AnsiString Value);

Description

SetEditText is called by the inplace editor so that the grid can store the new value for the current cell. The SetEditText method for TCustomGrid does nothing. Descendants of TCustomGrid override this method to update an internal representation of the cell’s value, or to generate an OnSetEditText event.


TCustomGrid::ShowEditor

TCustomGrid	See also

Displays the inplace editor when the grid enters edit mode.

void __fastcall ShowEditor(void);

Description

Grid controls call ShowEditor when the grid enters edit mode. ShowEditor displays the window of the inplace editor over the currently selected cell. If the inplace editor does not yet exist, ShowEditor creates it.


TCustomGrid::ShowEditorChar

TCustomGrid	See also

Displays the inplace editor, with its text set to the specified character.

void __fastcall ShowEditorChar(char Ch);

Description

Grid controls call ShowEditorChar when the user types a character into a cell and the editor is not already showing. ShowEditorChar displays the window of the inplace editor over the currently selected cell, and sets its text property to the character Ch. If the inplace editor does not yet exist, ShowEditorChar creates it.


TCustomGrid::SizeChanged

TCustomGrid	See also

Responds to changes in the size of the grid.

DYNAMIC void __fastcall SizeChanged(int OldColCount, int OldRowCount);

Description

SizeChanged provides the interface for a method that responds to changes in the number of rows or columns in the grid. The SizeChanged method of TCustomGrid does nothing. Descendants of TCustomGrid override this method to make internal adjustments or generate events.


TCustomGrid::Sizing

TCustomGrid	See also

Indicates whether the indicated coordinates are on one of the resize hot zones of the graph.

bool __fastcall Sizing(int X, int Y);

Description

Grid controls call Sizing internally with the coordinates of a mouse click to determine whether the user is about to resize a row or column.


TCustomGrid::TimedScroll

TCustomGrid	See also

Extends a move, resize, or selection out of the scrollable region when the user drags the mouse in a direction where the grid is scrolled.

enum Grids__4 { sdLeft, sdRight, sdUp, sdDown };

typedef Set<Grids__4, sdLeft, sdDown>  TGridScrollDirection;

DYNAMIC void __fastcall TimedScroll(TGridScrollDirection Direction);

Description

TimedScroll is called periodically as the user continues to drag with the mouse outside of the scrollable cells in the grid. TimedScroll does nothing unless the user is moving a row or column, resizing a row or column, or selecting a multiple cell region using the mouse. TimedScroll scrolls the cells in the grid to allow the operation to continue into the portion of the grid that was hidden due to scrolling.


TCustomGrid::TopLeftChanged

TCustomGrid	See also

Updates the position of the inplace editor when the grid scrolls.

DYNAMIC void __fastcall TopLeftChanged(void);

Description

Grid controls call TopLeftChanged internally, whenever the LeftCol or TopRow property changes.

Descendants of TCustomGrid override this method to make additional adjustments or to generate an OnTopLeftChanged event.


TCustomGrid::UpdateDesigner

TCustomGrid	See also

Notifies the designer when rows and columns of the grid are moved or resized.

void __fastcall UpdateDesigner(void);

Description

At design time, the designer automatically keeps track of property changes so that it can prompt the user to save any changes. Moving or resizing the rows and columns of the grid using the mouse bypasses this system. When such changes occur, UpdateDesigner notifies the designer that the properties of the grid have changed and that the changes should be saved.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


TCustomHotKey

Hierarchy	Properties	Methods

TCustomHotKey is the abstract base class for the hot key object that is a wrapper for the Windows hot key Common Control.

Unit

comctrls

Description

TCustomHotKey is an abstract class that encapsulates behavior of an object that is used to set a shortcut property at runtime. Hot key objects are used to perform an action quickly by enabling users to link the hot key to a combination of keystrokes that will execute the action. TCustomHotKey introduces properties to:

•	Associate the hot key with keystrokes to perform an action

•	Select a key combination at design time

•	Invalidate specific modifier keys

To change the key combination at runtime hold down the Alt, Ctrl or Shift keys or combinations of them and type a letter or number. The hot key property can then be assigned to the shortcut property of a menu item, for example.

Hot key classes that descend from TCustomHotKey inherit the basic functionality of TCustomHotKey. Use TCustomHotKey as a base class for deriving specialized hot key objects.


TCustomHotKey properties

TCustomHotKey	Alphabetically	Legend

In TCustomHotKey

AutoSize

HotKey

InvalidKeys

Modifiers

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

Derived from TComponent

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag


TCustomHotKey properties

TCustomHotKey	By object	Legend

Align

AutoSize

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

HotKey

InvalidKeys

Left

Modifiers

Name

Owner

Parent

ShowHint

Showing

TabOrder

TabStop

Tag

Top

Visible

Width


TCustomHotKey::AutoSize

TCustomHotKey

Determines whether the hot key automatically changes its height to accommodate the font size.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=1};

Description

Use AutoSize to fully display the font on the hot key control. When AutoSize is true, the height of the hot key changes to display the key combinations typed in it. When AutoSize is false, the hot key remains the same height, regardless of any font changes. The default value is true.


TCustomHotKey::HotKey

TCustomHotKey	See also 	Example

Contains the current key combination of the hot key control.

__property Menus::TShortCut HotKey = {read=GetHotKey, write=SetHotKey, nodefault};

Description

Use HotKey to set or change the key combination associated with the hot key. Alt+A is the default. To modify the value of HotKey either edit it directly or set the value of the Modifiers property. At runtime, HotKey is reset when the hot key has focus and the user presses valid key combinations.


TCustomHotKey::InvalidKeys

TCustomHotKey	See also 	Example

Allows you to specify that one or more modifier keys should be considered invalid.

__property THKInvalidKeys InvalidKeys = {read=FInvalidKeys, write=SetInvalidKeys, nodefault};

Description

Use InvalidKeys to select which modifier keys are not allowed. If this property is set, a default modifier should also be specified in the Modifiers property. When the invalid key is selected, the default modifier is displayed in its place.

THKInvalidKey is the type of the InvalidKeys property. These are the possible values:

Value	Meaning

hcNone	Unmodified keys are invalid.

hcShift	The Shift key is invalid as a modifier.

hcCtrl	The Ctrl key is invalid as a modifier.

hcAlt	The Alt key is invalid as a modifier.

hcShiftCtrl	The Shift+Ctrl key combination is invalid as a modifier.

hcShiftAlt	The Shift+Alt key combinations invalid as a modifier.

hcCtrlAlt	The Ctrl+Alt key combination is invalid as a modifier.

hcShiftCtrlAlt	The Shift+Ctrl+Alt key combination is invalid as a modifier.

The default values are hcNone and hcShift.


TCustomHotKey::Modifiers

TCustomHotKey 	Example

Specifies the key or keys that are used with a non-modifier key.

__property THKModifiers Modifiers = {read=FModifiers, write=SetModifiers, nodefault};

Description

Use Modifiers to select a modifier key such as Ctrl, Alt, or Shift for the hot key. These are the possible values:

Value	Meaning

hkShift	The Shift key is used as a modifier.

hkCtrl	The Ctrl key is used as a modifier.

hkAlt	The Alt key is used as a modifier.

hkExt	The Extra key is used as a modifier.

The default value is hkAlt.

Modifier keys are used in combination with another non-modifier key such as character and function keys, arrow keys, and so on. More than one modifier key can be used.


TCustomHotKey methods

TCustomHotKey	Alphabetically

In TCustomHotKey

~TCustomHotKey

TCustomHotKey

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

GetParentComponent

HasParent

InsertComponent

RemoveComponent

Derived from TPersistent

Assign

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomHotKey methods

TCustomHotKey	By object

~TCustomHotKey

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomHotKey

Update

UpdateControlState


TCustomHotKey::TCustomHotKey

TCustomHotKey	See also

Instantiates a hot key control.

__fastcall virtual TCustomHotKey(Classes::TComponent* AOwner);

Description

Call TCustomHotKey to instantiate a hot key control at runtime. For hot key controls created at design time, TCustomHotKey is called automatically.

TCustomHotKey allocates memory for a hot key control and calls the parent object's constructor. Then it sets default values for the Width and Height properties, and initializes the following properties:

•	TabStop to true

•	ParentColor to false

•	AutoSize to true

•	InvalidKeys to hcNone and hcShift

•	Modifiers to [hkAlt]

•	HotKey to 'Alt+A'


TCustomHotKey::~TCustomHotKey

TCustomHotKey

Frees the memory associated with the TCustomHotKey object.

__fastcall virtual ~TCustomHotKey(void) { }

Description

Do not call ~TCustomHotKey directly. Instead, use the delete keyword.


Scope

Protected

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomIniFile

Hierarchy	Properties	Methods	See also

TCustomIniFile is the abstract base type for components that encapsulate access to 16-bit Windows 3.x INI files.

Unit

inifiles

Description

Use TCustomIniFile as a base class when defining components that access INI files. TCustomIniFile introduces properties and methods to handle storage and retrieval of application-specific information and settings in a Windows 3.x INI file.

Do not create instances of TCustomIniFile. Instead, use or create descendents of TCustomIniFile, such as TIniFile and TMemIniFile.

Note:

TCustomIniFile is supported only for migration purposes and backward compatibility. 32-bit Windows replaces INI files with a system registry where all applications store and retrieve their settings. Applications that target 32-bit Windows should use the system registry instead of INI files. C++Builder provides objects for handling the system registry, such as TRegistry. TRegistryIniFile also encapsulates the registry, but provides an easier migration path for existing Windows 3.1 applications that are upgraded 32-bit Windows.


TCustomIniFile properties

TCustomIniFile	Alphabetically	Legend

In TCustomIniFile

FileName


TCustomIniFile properties

TCustomIniFile	By object	Legend

FileName


TCustomIniFile::FileName

TCustomIniFile	See also

Contains the name of the INI file from which to read and to which to write application-specific information.

__property System::AnsiString FileName = {read=FFileName};

Description

Use FileName to examine the name of the INI file used by the application for its application settings and information. The methods that read and write INI file information automatically handle opening and closing the file specified by FileName.

FileName is read-only. The name of the INI file the object uses is supplied as the parameter for the Create method.

Note:	Usually INI files are stored in the \WINDOWS directory. To work with an INI file in another location, specify the full path name of the file in the FileName parameter passed to the Create method of TCustomIniFile.


TCustomIniFile methods

TCustomIniFile	Alphabetically

In TCustomIniFile

~TCustomIniFile

DeleteKey

EraseSection

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

SectionExists

TCustomIniFile

UpdateFile

ValueExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomIniFile methods

TCustomIniFile	By object

~TCustomIniFile

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DeleteKey

Dispatch

EraseSection

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

SectionExists

TCustomIniFile

UpdateFile

ValueExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime


TCustomIniFile::TCustomIniFile

TCustomIniFile	See also

Creates a TCustomIniFile object for an application.

__fastcall TCustomIniFile(const System::AnsiString FileName);

Description

Call TCustomIniFile to construct a TCustomIniFile object for an application. TCustomIniFile inherits TCustomIniFile from TObject, and creates an additional property, FileName, which is used to specify the name of the INI file to use.

Note:	Usually INI files are stored in the \WINDOWS directory. To work with an INI file in another location, specify the full path name of the file in FileName.


TCustomIniFile::DeleteKey

TCustomIniFile	See also 	Example

Erases the data value associated with an INI file entry.

virtual void __fastcall DeleteKey(const System::AnsiString Section, const System::AnsiString Ident) = 0;

Description

Call DeleteKey to erase a data value associated with an INI file entry. Section is string containing the name of an INI file section, and Ident is a string containing the name of the key from for which to set a NULL value.

Note:	Attempting to erase a data value in a non-existent section or attempting to erase data from a non-existent key are not errors. In these cases, DeleteKey creates the section and key and sets its initial value to an empty value.


TCustomIniFile::EraseSection

TCustomIniFile	See also

Erases an entire section of an INI file.

virtual void __fastcall EraseSection(const System::AnsiString Section) = 0;

Description

Call EraseSection to remove a section, all its keys, and their data values from an INI file. Section identifies the INI file section to remove. If a section cannot be removed, an exception is raised.


TCustomIniFile::ReadBool

TCustomIniFile	See also 	Example

Retrieves a Boolean value from an INI file.

virtual bool __fastcall ReadBool(const System::AnsiString Section, const System::AnsiString Ident, bool Default);

Description

Call ReadBool to read a Boolean value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the Boolean value. Default is the Boolean value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::ReadDate

TCustomIniFile	See also

Retrieves a date value from an INI file.

virtual System::TDateTime __fastcall ReadDate(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Default);

Description

Call ReadDate to read a date value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the date value. Default is the date value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::ReadDateTime

TCustomIniFile	See also

Retrieves a date-time value from an INI file.

virtual System::TDateTime __fastcall ReadDateTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Default);

Description

Call ReadDateTime to read a date-time value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the date-time value. Default is the date-time value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::ReadFloat

TCustomIniFile	See also

Retrieves a float value from an INI file.

virtual double __fastcall ReadFloat(const System::AnsiString Section, const System::AnsiString Name, double Default);

Description

Call ReadFloat to read a float value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the float value. Default is the float value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::ReadInteger

TCustomIniFile	See also 	Example

Retrieves an integer value from an INI file.

virtual int __fastcall ReadInteger(const System::AnsiString Section, const System::AnsiString Ident, int Default);

Description

Call ReadInteger to read an integer value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the value. Default is the integer value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::ReadSection

TCustomIniFile	See also

Reads all the key names from a specified section of an INI file into a string list.

virtual void __fastcall ReadSection(const System::AnsiString Section, Classes::TStrings* Strings) = 0;

Description

Call ReadSection to retrieve the names of all keys within a specified section of an INI file into a string list object.

Section identifies the section from which to retrieve a list of key names. Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object such as a string list, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TCustomIniFile::ReadSections

TCustomIniFile	See also

Reads the names of all sections in an INI file into a string list.

virtual void __fastcall ReadSections(Classes::TStrings* Strings) = 0;

Description

Call ReadSections to retrieve the names of all sections in an INI file into a string list object.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TCustomIniFile::ReadSectionValues

TCustomIniFile	See also 	Example

Reads the values from all keys within a section of an INI file into a string list.

virtual void __fastcall ReadSectionValues(const System::AnsiString Section, Classes::TStrings* Strings) = 0;

Description

Call ReadSectionValues to read the values from all keys within a specified section of an INI file into a string list object. Section identifies the section in the file from which to read key values. Strings is the string list object into which to read the values.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TCustomIniFile::ReadString

TCustomIniFile	See also 	Example

Retrieves a string value from an INI file.

virtual System::AnsiString __fastcall ReadString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Default) = 0;

Description

Call ReadString to read a string value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the value. Default is the string value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::ReadTime

TCustomIniFile	See also

Retrieves a time value from an INI file.

virtual System::TDateTime __fastcall ReadTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Default);

Description

Call ReadTime to read a time value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the time value. Default is the time value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TCustomIniFile::SectionExists

TCustomIniFile	See also

Indicates whether a section exists in the INI file.

bool __fastcall SectionExists(const System::AnsiString Section);

Description

Use SectionExists to determine whether a section exists within the INI file specified in FileName.

Section is the INI file section SectionExists determines the existence of.

SectionExists returns a Boolean value that indicates whether the section in question exists.


TCustomIniFile::UpdateFile

TCustomIniFile	See also

Flushes buffered INI file data to disk.

virtual void __fastcall UpdateFile(void) = 0;

Description

Call UpdateFile to flush buffered reads from and writes to the INI file to disk. UpdateFile is useful under Windows95, but has no effect under Windows NT as NT does not buffer INI file reads and writes.


TCustomIniFile::ValueExists

TCustomIniFile	See also

Indicates whether a key exists in the INI file.

bool __fastcall ValueExists(const System::AnsiString Section, const System::AnsiString Ident);

Description

Use ValueExists to determine whether a key exists in the INI file specified in Filename.

Section is the section in the INI file in which to search for the key.

Ident is the name of the key to search for.

ValueExists returns a Boolean value that indicates whether the key exists in the specified section.


TCustomIniFile::WriteBool

TCustomIniFile	See also 	Example

Writes a Boolean value to an INI file.

virtual void __fastcall WriteBool(const System::AnsiString Section, const System::AnsiString Ident, bool Value);

Description

Call WriteBool to write a Boolean value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the Boolean value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteBool creates the section and key and sets its initial value to Value.


TCustomIniFile::WriteDate

TCustomIniFile	See also

Writes a date value to an INI file.

virtual void __fastcall WriteDate(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteDate to write a date value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the date value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteDate creates the section and key and sets its initial value to Value.


TCustomIniFile::WriteDateTime

TCustomIniFile	See also

Writes a date-time value to an INI file.

virtual void __fastcall WriteDateTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteDateTime to write a date-time value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the date-time value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteDateTime creates the section and key and sets its initial value to Value.


TCustomIniFile::WriteFloat

TCustomIniFile	See also

Writes a float value to an INI file.

virtual void __fastcall WriteFloat(const System::AnsiString Section, const System::AnsiString Name, double Value);

Description

Call WriteFloat to write a float value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the float value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteFloat creates the section and key and sets its initial value to Value.


TCustomIniFile::WriteInteger

TCustomIniFile	See also 	Example

Writes an integer value to an INI file.

virtual void __fastcall WriteInteger(const System::AnsiString Section, const System::AnsiString Ident, int Value);

Description

Call WriteInteger to write an integer value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the integer value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteInteger creates the section and key and sets its initial value to Value.


TCustomIniFile::WriteString

TCustomIniFile	See also 	Example

Writes a string value to an INI file.

virtual void __fastcall WriteString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Value) = 0;

Description

Call WriteString to write a string value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the string value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteString creates the section and key and sets its initial value to Value.


TCustomIniFile::WriteTime

TCustomIniFile	See also

Writes a time value to an INI file.

virtual void __fastcall WriteTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteTime to write a time value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the time value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteTime creates the section and key and sets its initial value to Value.


TCustomIniFile::~TCustomIniFile

TCustomIniFile

~TCustomIniFile frees the memory associated with the TCustomIniFile object.

__fastcall virtual ~TCustomIniFile(void) { }

Description

Do not call ~TCustomIniFile directly. Instead, use the delete keyword on the object, which causes ~TCustomIniFile to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject


TCustomImageList

Hierarchy	Properties	Methods	Events	See also

TCustomImageList is the abstract base class for collections of same-sized images, each of which can be referred to by its index.

Unit

controls

Description

Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks that are combined with the images to produce a transparent effect such as is common in icons.


TCustomImageList properties

TCustomImageList	Alphabetically	Legend

In TCustomImageList

AllocBy

BkColor

BlendColor

Count

DragCursor

Dragging

DrawingStyle

Handle

Height

ImageType

Masked

ShareImages

Width

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomImageList properties

TCustomImageList	By object	Legend

AllocBy

BkColor

BlendColor

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Count

DesignInfo

DragCursor

Dragging

DrawingStyle

Handle

Height

ImageType

Masked

Name

Owner

ShareImages

Tag

VCLComObject

Width


TCustomImageList::AllocBy

TCustomImageList	See also

Sets the number of images by which the image list will grow when it needs to make room for new images.

__property int AllocBy = {read=FAllocBy, write=FAllocBy, default=4};

Description

Use the AllocBy method to specify the number of new images that can be added to the resized image list.


TCustomImageList::BkColor

TCustomImageList	See also

Determines which background color to use when drawing an image.

__property Graphics::TColor BkColor = {read=GetBkColor, write=SetBkColor, default=536870911};

Description

Use BkColor to specify the color used for the masked regions of the images in the list.  When BkColor is clNone, the image is drawn transparently using the mask to define the transparent areas. Otherwise, the value of BkColor appears in the masked out portions.

Note:	BkColor has no effect when the Masked property is false.


TCustomImageList::BlendColor

TCustomImageList	See also

Determines which foreground color to use when drawing an image.

__property Graphics::TColor BlendColor = {read=FBlendColor, write=FBlendColor, default=536870911};

Description

Set BlendColor to cause the images in the list to be combinded with the specified color when the DrawingStyle is dsFocus or dsSelected.  More of BlendColor is combined with the images when DrawingStyle is dsSelected.  clNone specifies no blend color while clDefault specifies the system highlight.


TCustomImageList::Count

TCustomImageList	See also

Specifies the number of images in the image list.

__property int Count = {read=GetCount, nodefault};

Description

Use Count when iterating through the images in the image list.  Retrieve the individual images using the GetBitmap method.  Draw individual images using the Draw method.


TCustomImageList::DragCursor

TCustomImageList	See also

Specifies the current drag cursor that is associated with the image list.

__property TCursor DragCursor = {read=FDragCursor, write=SetDragCursor, nodefault};

Description

Use the DragCursor property to determine which drag cursor should be displayed when an image in the image list is dragged. When an image is dragged, a new drag image is created by combining the given image (typically a mouse cursor image) with the current drag cursor.


TCustomImageList::Dragging

TCustomImageList	See also

Indicates whether an image in the image list is being dragged.

__property bool Dragging = {read=FDragging, nodefault};

Description

When Dragging returns true, an image in the image list is being dragged. When Dragging returns false, no image is being dragged.


TCustomImageList::DrawingStyle

TCustomImageList	See also

Specifies the style to be used when the image list is drawing an image.

__property TDrawingStyle DrawingStyle = {read=FDrawingStyle, write=FDrawingStyle, default=2};

Description

Use the DrawingStyle property to control how the image is to appear. These are the possible values:

Value	Meaning

dsFocused	Draws the image blending 25% with the color specified by the BlendColor property. This only affects image lists that contain masks.

dsSelected	Draws the image blending 50% with the color specified by the BlendColor property. This only affects image lists that contain masks.

dsNormal	Draws the image using the color specified in the BkColor property. If the BkColor is clNone, the image is drawn transparently using the mask.

dsTransparent	Draws using the mask regardless of the BkColor setting.


TCustomImageList::Handle

TCustomImageList	See also

Designates the handle for the image list.

__property int Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

The Handle property is the Windows image list object handle.  Use this handle when calling Windows API functions that require it.


TCustomImageList::Height

TCustomImageList	See also

Specifies the height of images within the image list.

__property int Height = {read=FHeight, write=SetHeight, nodefault};

Description

Use the Height property to specify the height of images before any are added to the image list. The image list is cleared when this value changes.


TCustomImageList::ImageType

TCustomImageList	See also

Determines whether the image list uses the image or the associated image mask when drawing.

__property TImageType ImageType = {read=FImageType, write=FImageType, default=0};

Description

Use the ImageType property to control how the image is to appear. These are the possible values:

Value	Meaning

itImage	Draws the image.

itMask	Draws the mask.


TCustomImageList::Masked

TCustomImageList	See also

Specifies whether the image list includes masks that can be combined with the images.

__property bool Masked = {read=FMasked, write=FMasked, default=1};

Description

Set the Masked property to true to combine the images with masks.  The masked portion of the bitmap will be drawn transparently, or replaced by the color specified by the BkColor property.


TCustomImageList::ShareImages

TCustomImageList	See also

Specifies whether the image list destroys its handle when the image list is destroyed.

__property bool ShareImages = {read=FShareImages, write=FShareImages, default=0};

Description

Set the ShareImages property to false to ensure that the handle to the image list is freed when the image list is destroyed.


TCustomImageList::Width

TCustomImageList	See also

Specifies the width of all images within the image list.

__property int Width = {read=FWidth, write=SetWidth, default=16};

Description

Use the Width property to specify the width of images before any are added to the image list. The image list is cleared when this value changes.


TCustomImageList events

TCustomImageList	Alphabetically	Legend

In TCustomImageList

OnChange


TCustomImageList events

TCustomImageList	By object	Legend

OnChange


TCustomImageList::OnChange

Occurs when the image list changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Write an OnChange event handler to execute code when the image list changes. Any objects registered with the RegisterChanges method will also be notified.


TCustomImageList methods

TCustomImageList	Alphabetically	Legend

In TCustomImageList

~TCustomImageList

Add

AddIcon

AddImages

AddMasked

Assign

BeginDrag

Change

Clear

CreateSize

DefineProperties

Delete

DragLock

DragMove

DragUnlock

Draw

DrawOverlay

EndDrag

FileLoad

GetBitmap

GetHotSpot

GetIcon

GetImageBitmap

GetImages

GetInstRes

GetMaskBitmap

GetResource

HandleAllocated

HandleNeeded

HideDragImage

Initialize

Insert

InsertIcon

InsertMasked

Move

Overlay

RegisterChanges

Replace

ReplaceIcon

ReplaceMasked

ResInstLoad

ResourceLoad

SetDragImage

ShowDragImage

TCustomImageList

UnRegisterChanges

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomImageList methods

TCustomImageList	By object	Legend

~TCustomImageList

Add

AddIcon

AddImages

AddMasked

Assign

BeginDrag

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

CreateSize

DefaultHandler

DefineProperties

Delete

DestroyComponents

Destroying

Dispatch

DragLock

DragMove

DragUnlock

Draw

DrawOverlay

EndDrag

FieldAddress

FileLoad

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetBitmap

GetHotSpot

GetIcon

GetImageBitmap

GetImages

GetInstRes

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMaskBitmap

GetNamePath

GetParentComponent

GetResource

HandleAllocated

HandleNeeded

HasParent

HideDragImage

InheritsFrom

Initialize

InitInstance

Insert

InsertComponent

InsertIcon

InsertMasked

InstanceSize

MethodAddress

MethodName

Move

NewInstance

Overlay

RegisterChanges

RemoveComponent

Replace

ReplaceIcon

ReplaceMasked

ResInstLoad

ResourceLoad

SafeCallException

SetDragImage

ShowDragImage

TCustomImageList

UnRegisterChanges


TCustomImageList.Add

TCustomImageList	See also

Adds an Image and its Mask to the image list object.

int __fastcall Add(Graphics::TBitmap* Image, Graphics::TBitmap* Mask);

Description

Use the Add method to add images with their masks to an image list. It returns the index of the added image, or -1 if it fails. When the Masked property of the image list is false, the second bitmap handle is ignored; it can be set to NULL.


TCustomImageList::AddIcon

TCustomImageList	See also

Adds an icon to the image list object.

int __fastcall AddIcon(Graphics::TIcon* Image);

Description

Use the AddIcon method to add the icon specified by the Image parameter to an image list. AddIcon returns the index of the added image, or -1 if it fails.


TCustomImageList::AddImages

TCustomImageList	See also

Adds images from another image list to the image list object.

void __fastcall AddImages(TCustomImageList* Value);

Description

Use the AddImages method to add the images from another image list. Value specifies the source image list. AddImages returns -1 if it fails, 0 if it’s successful.


TCustomImageList::AddMasked

TCustomImageList	See also

Adds an image to the image list along with a color which is used to generate the transparent mask.

int __fastcall AddMasked(Graphics::TBitmap* Image, Graphics::TColor MaskColor);

Description

AddMasked is similar to Add except that a mask bitmap is not specified. Instead, a color that the system combines with the image bitmap to automatically generate the masks is specified. Each pixel of the specified color in the image bitmap is changed to black, and the corresponding bit in the mask is set to one. As a result, any pixel in the image that matches the specified color is transparent when the image is drawn. AddMasked returns -1 if it fails, 0 if it’s successful.


TCustomImageList::Assign

TCustomImageList	See also

Copies the information from one image list to another.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

If Source is another TImageList object, Assign discards any current image information and replaces it with the information from Source. If Source is any other type of object, Assign calls its inherited method. Use this method to copy one object's information to another.


TCustomImageList::BeginDrag

TCustomImageList	See also

Starts the dragging of an image.

bool __fastcall BeginDrag(HWND Window, int X, int Y);

Description

Use the BeginDrag method to start dragging an image set by SetDragImage at the X and Y coordinates of the drag position relative to the upper-left corner of the image. Window is the handle to the image list. BeginDrag returns true if it was successful in starting the drag of the image.


TCustomImageList::Change

TCustomImageList	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(void);

Description

Change calls the OnChange event handler if it is assigned.  Override Change to block this event or provide additional responses to changes in the image list.


TCustomImageList::Clear

TCustomImageList	See also

Clears all images from the image list.

void __fastcall Clear(void);

Description

Use the Clear method to remove all images from the image list. Use the Delete method to delete one image from the image list.


TCustomImageList::TCustomImageList

TCustomImageList	See also

Creates an empty image list.

__fastcall virtual TCustomImageList(Classes::TComponent* AOwner);

Description

Use TCustomImageList to instantiate an image list at runtime. ImageLists placed on forms at design time are created automatically.  Specify the owner of the new imagelist using the Aowner parameter.

The new imagelist contains no images and has a default size of 16 by 16 pixels.


TCustomImageList::TCustomImageList
TCustomImageList::CreateSize

TCustomImageList	See also

Creates an empty image list of a specified size.

__fastcall TImageList(int AWidth, int AHeight) : Controls::TCustomImageList(AWidth, AHeight) { }

Description

Use CreateSize to create an image list object at runtime with an image size other than the default of 16 x 16 pixels. The initial size of the image list is determined by the AHeight and AWidth parameters. The height and width can be altered after the image list has been created using the Width and Height properties.


TCustomImageList::DefineProperties

TCustomImageList	See also

Allows bitmap data to be saved and loaded.

virtual void __fastcall DefineProperties(Classes::TFiler* Filer);

Description

After calling the inherited method, DefineProperties calls Filer’s DefineBinaryProperty method, which enables the filer to load and save the bitmap data as if it were a property.


TCustomImageList::Delete

TCustomImageList	See also

Deletes a particular image from the image list.

void __fastcall Delete(int Index);

Description

Use the Delete method to delete an image specified by Index in the image list. Use the Clear method to delete all images in the image list.


TCustomImageList::~TCustomImageList

TCustomImageList	See also

Destroys the image list and releases the memory allocated to it.

__fastcall virtual ~TCustomImageList(void);

Description

Do not call ~TCustomImageList directly. Instead, use the delete keyword.


TCustomImageList::DragLock

TCustomImageList	See also

Associates the drag image with a Window and draws it at a specified position while that window is in drag mode.

bool __fastcall DragLock(HWND Window, int XPos, int YPos);

Description

Call DragLock to use an image in the image list as a drag image for the window specified by the Window parameter.  Specify the current drag position of the window using the XPos and YPos parameters. DragLock returns true if successful.


TCustomImageList::DragMove

TCustomImageList	See also

Moves the drag image set by SetDragImage to a new position.

bool __fastcall DragMove(int X, int Y);

Description

Use DragMove to move the image that is being dragged during a drag-and-drop operation. DragMove moves the image to the position specified by X and Y. It returns true if successful.


TCustomImageList::DragUnlock

TCustomImageList	See also

Removes the association between a drag image and a window.

void __fastcall DragUnlock(void);

Description

Use the DragUnlock method when an image is no longer needed as a drag image for a particular window.


TCustomImageList::Draw

TCustomImageList	See also 	Example

Draws the image specified by the Index parameter onto the provided Canvas.

void __fastcall Draw(Graphics::TCanvas* Canvas, int X, int Y, int Index);

Description

Use the Draw method to draw one of the images in the image list onto Canvas. The image is drawn at the position X, Y according to the style set in the DrawingStyle property.


TCustomImageList::DrawOverlay

TCustomImageList	See also

Draws an image and an overlay onto the provided Canvas.

void __fastcall DrawOverlay(Graphics::TCanvas* Canvas, int X, int Y, int ImageIndex, TOverlay Overlay);

Description

An overlay mask is an image drawn transparently over another image. Any image can be used as an overlay mask. To draw an overlay mask over an image use the DrawOverlay method with the index of the overlay mask. The Overlay method must be called first to allow an image to be used as an overlay.


TCustomImageList::EndDrag

TCustomImageList	See also

Ends the drag operation.

bool __fastcall EndDrag(void);

Description

Use EndDrag to end a drag operation that was started using the BeginDrag method. EndDrag returns true if successful.


TCustomImageList::FileLoad

TCustomImageList	See also

Loads a resourced image into the image list.

bool __fastcall FileLoad(TResType ResType, System::AnsiString Name, Graphics::TColor MaskColor);

Description

Use the FileLoad method to load a bitmap, cursor, or icon from a resource file. Use ResType to specify the type of resource. Use Name to identify the resource by name, or, if the resource has no name, by converting its number using MAKEINTRESOURCE. Use MaskColor to set the transparent color for the images. FileLoad returns true if successful.

Note:	Within a package, FileLoad will return an error. GetInstRes must be used to load a resource from within a package.


TCustomImageList::GetBitmap

TCustomImageList	See also

Retrieves a specified image as a bitmap.

void __fastcall GetBitmap(int Index, Graphics::TBitmap* Image);

Description

Use the GetBitmap method to obtain a particular image in the image list as a bitmap object. Index denotes the index of the image. The bitmap is returned as the Image parameter.


TCustomImageList::GetHotSpot

TCustomImageList	See also

Returns the hot spot location associated with the current drag image.

tagPOINT __fastcall GetHotSpot();

Description

Use the GetHotSpot method to obtain the position of the hot spot of the current drag image.


TCustomImageList::GetIcon

TCustomImageList	See also

Returns the image specified by Index as an icon into the Image parameter.

void __fastcall GetIcon(int Index, Graphics::TIcon* Image);

Description

Use the GetIcon method to obtain a particular image in the image list as an icon.


TCustomImageList::GetInstRes

TCustomImageList	See also

Loads a specified bitmap, cursor, or icon resource into the image list.

bool __fastcall GetInstRes(int Instance, TResType ResType, System::AnsiString Name, int Width, TLoadResources LoadFlags, Graphics::TColor MaskColor);

Description

Use the GetInstRes method to load bitmap, cursor, or icon resource into an image list.

Use Instance to specify the instance handle of the resource module. Use ResType to indicate the type of resource (rtBitmap, rtCursor or rtIcon). Use Name to identify the resource by name, or, if the resource has no name, by converting its number using MAKEINTRESOURCE. Use MaskColor to set the transparent color for the image. LoadFlags specifies how to load the image. A combination of the following values can be used.

Value	Meaning

lrNone	No specific resource flags.

lrDefaultColor	Use the color format of the display.

lrDefaultSize	Use system metrics for Height and Width if the Width parameter to GetResource is 0. If the Width parameter is 0 and this option is not specified for cursors and icons, the resources width and height will be used.

lrFromFile	Loads the resource from the specified file.

lrMap3DColors	Replaces the images grey shades with the 3D windows colors.

lrTransparent	Replaces the color table entry for the first pixel of the resource with the default window color (COLOR_WINDOW). This applies only to images with color tables.

lrMonoChrome	Loads the resource as black and white.

Note:	GetInstRes must be used to load a resource from within a package. Within a package, GetResouce or FileLoad return an error.


TCustomImageList::GetImageBitmap

TCustomImageList	See also

Returns a handle to a bitmap containing all of the images in the image list.

HBITMAP __fastcall GetImageBitmap(void);

Description

Use the GetImageBitmap method to obtain a bitmap that contains all images in the image list. GetImageBitmap returns 0 if unsuccessful.


TCustomImageList::GetImages

TCustomImageList	See also

Returns a specified image and its mask as bitmaps.

void __fastcall GetImages(int Index, Graphics::TBitmap* Image, Graphics::TBitmap* Mask);

Description

Use GetImages to obtain the image (and its mask) identified by the Index parameter. The Image is returned as the Image parameter, and the Mask as the Mask parameter.


TCustomImageList::GetMaskBitmap

TCustomImageList	See also

Returns a handle to a bitmap containing all masks for images in the image list.

HBITMAP __fastcall GetMaskBitmap(void);

Description

Use the GetMaskBitmap to obtain a bitmap that contains all masks in the image list. GetMaskBitmap returns 0 if unsuccessful.


TCustomImageList::GetResource

TCustomImageList	See also

Loads the specified bitmap, cursor, or icon resource into the image list.

bool __fastcall GetResource(TResType ResType, System::AnsiString Name, int Width, TLoadResources LoadFlags, Graphics::TColor MaskColor);

Description

Use the GetResource method to load bitmap, cursor, or icon resource into an image list.

Note:	Within a package, GetResouce returns an error. GetInstRes must be used to load a resource from within a package.

ResType specifies the type of graphical resource that is to be loaded into the image list and can be rtBitmap, rtCursor or rtIcon. Use Name to identify the resource by name, or, if the resource has no name, by converting its number using MAKEINTRESOURCE. Use MaskColor to set the transparent color for the images in the file. LoadFlags specifies how to load the image. A combination of the following values can be used.

Value	Meaning

lrNone	No specific resource flags.

lrDefaultColor	Use the color format of the display.

lrDefaultSize	Use system metrics for Height and Width if the Width parameter to GetResource is 0. If the Width parameter is 0 and this option is not specified for cursors and icons, the resources width and height will be used.

lrFromFile	Loads the resource from the specified file.

lrMap3DColors	Replaces the images grey shades with the 3D windows colors.

lrTransparent	Replaces the color table entry for the first pixel of the resource with the default window color (COLOR_WINDOW). This applies only to images with color tables.

lrMonoChrome	Loads the resource as black and white.


TCustomImageList::HandleAllocated

TCustomImageList	See also

Indicates whether a window handle exists for the image list.

bool __fastcall HandleAllocated(void);

Description

Use HandleAllocated to determine if a handle exists for the image list. HandleAllocated returns true if the Windows image list has been created and a handle is available, false otherwise. HandleAllocated doesn’t create a handle if it doesn’t already exist.

Note:	Getting the Handle property of creates the Windows image list automatically if it didn't previously exist, and returns the resulting handle.


TCustomImageList::HandleNeeded

TCustomImageList	See also

Creates an image list handle for the image list if one doesn't already exist.

void __fastcall HandleNeeded(void);

Description

Use HandleNeeded to create an Windows image list for the image list component when one doesn’t already exist. This method is called automatically when an image list’s handle property is accessed.


TCustomImageList::HideDragImage

TCustomImageList	See also

Hides the current drag image if it was previously shown.

void __fastcall HideDragImage(void);

Description

Use the HideDragImage method to hide the current drag image.


TCustomImageList::Initialize

TCustomImageList	See also

Initializes a newly allocated image list.

void __fastcall Initialize(void);

Description

Initialize is called from the Create and CreateSize constructors of the image list. It sets numerous image list properties to their default values and creates instances of helper objects used internally.


TCustomImageList::Insert

TCustomImageList	See also

Inserts a bitmap and its mask into the image list following a specified image.

HIDESBASE void __fastcall Insert(int Index, Graphics::TBitmap* Image, Graphics::TBitmap* Mask);

Description

Use the Insert method to insert a bitmap and its mask into the image list.  The image is inserted following the image specified by Index.


TCustomImageList::InsertIcon

TCustomImageList	See also

Inserts an icon at a specified position in the image list.

void __fastcall InsertIcon(int Index, Graphics::TIcon* Image);

Description

Use the InsertIcon method to insert an icon into the image list. The icon is inserted following the image specified by Index.


TCustomImageList::InsertMasked

TCustomImageList	See also

Inserts a bitmap at a specified position, creating the mask from a specified transparent color.

void __fastcall InsertMasked(int Index, Graphics::TBitmap* Image, Graphics::TColor MaskColor);

Description

Use the InsertMasked method to insert a masked image into the image list. The new image is inserted following the image specified by Index. Use MaskColor to identify the color in the image used to generate the Mask.


TCustomImageList::Move

TCustomImageList	See also

Moves a specified image to another position.

void __fastcall Move(int CurIndex, int NewIndex);

Description

Use the Move method to move an image to another position in the image list. Specify the current position using CurIndex, and the new position using NewIndex.


TCustomImageList::Overlay

TCustomImageList	See also

Adds the index of an image to the list of images to be used as overlay masks.

bool __fastcall Overlay(int ImageIndex, TOverlay Overlay);

Description

An overlay mask is an image drawn transparently over another image. Any image can be used as an overlay mask. To draw an overlay mask over an image use the DrawOverlay method with the index of the overlay mask. If successful, Overlay returns true.

Up to four indices can be added to the list.


TCustomImageList::RegisterChanges

TCustomImageList	See also

Registers an object to be notified when changes occur in the image list.

void __fastcall RegisterChanges(TChangeLink* Value);

Description

Use the RegisterChanges method to have an object notified whenever changes occur in the image list. The TChangeLink's OnChange event is called whenever a change in the image list occurs.

Create a change link object for each object that should be notified of changes. Register each object by calling RegisterChanges and passing its change link object as the Value parameter. The OnChange event of all registered change link objects is then triggered when a change occurs in the image list. Any code assigned to the OnChange event handlers will execute.


TCustomImageList::Replace

TCustomImageList	See also

Replaces an image in the image list with a new image and mask.

void __fastcall Replace(int Index, Graphics::TBitmap* Image, Graphics::TBitmap* Mask);

Description

Use the Replace method to replace the image at the Index position in the image list with a new Image and overlay Mask.


TCustomImageList::ReplaceIcon

TCustomImageList	See also

Replaces an image in the image list with an icon.

void __fastcall ReplaceIcon(int Index, Graphics::TIcon* Image);

Description

Use the ReplaceIcon method to replace the Image at the Index position in the image list with a new icon.


TCustomImageList::ReplaceMasked

TCustomImageList	See also

Replaces an image in the image list with a new image and mask.

void __fastcall ReplaceMasked(int Index, Graphics::TBitmap* NewImage, Graphics::TColor MaskColor);

Description

Use the ReplaceMasked method to replace the image at Index position within the image list with a new image and mask created using the MaskColor for transparency.


TCustomImageList::ResInstLoad

TCustomImageList	See also

Loads a resource into the image list.

bool __fastcall ResInstLoad(int Instance, TResType ResType, System::AnsiString Name, Graphics::TColor MaskColor);

Description

Use the ResoInstLoad method to load a resource of type TResType into the image list. Use Instance to specify the instance handle of the resource module, and Name to identify the resource within that module. MaskColor is used to create the mask for the resulting image. ResInstLoad should be used rather than ResouceLoad to load a resource from within a package.

ResInstLoad returns true if it is successful, false otherwise.


TCustomImageList::ResourceLoad

TCustomImageList	See also

Loads a resource into the image list.

bool __fastcall ResourceLoad(TResType ResType, System::AnsiString Name, Graphics::TColor MaskColor);

Description

Use the ResourceLoad method to load a resource of type TResType into the image list. Use Name to identify the resource. MaskColor is used to create the mask for the resulting image. ResourceLoad returns true if successful, false otherwise.

Note:	Within a package, ResouceLoad will return an error. ResInstLoad must be used to load a resource from within a package.


TCustomImageList::SetDragImage

TCustomImageList	See also

Sets an image within the image list to be shown during a drag and drop operation.

bool __fastcall SetDragImage(int Index, int HotSpotX, int HotSpotY);

Description

Use the SetDragImage method to set the image specified by Index within the image list to be shown when the image list is being used for drag and drop. The hot spot of the image is specified by HotSpotX and HotSpotY.


TCustomImageList::ShowDragImage

TCustomImageList	See also

Shows the current drag image if it was previously hidden.

void __fastcall ShowDragImage(void);

Description

Use ShowDragImage method to show the current drag image if it was previously hidden.


TCustomImageList::UnRegisterChanges

TCustomImageList	See also

Removes an object from the list of objects to be notified when the image list changes.

void __fastcall UnRegisterChanges(TChangeLink* Value);

Description

Use the UnRegisterChanges method to unregister a TChangeLink object. The object will no longer receive notification when the image list changes.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TCustomLabel

Hierarchy	Properties	Methods	See also

TCustomLabel is the base class for non-windowed controls that display text on a form.

Unit

stdctrls

Description

Use TCustomLabel as a base class when defining objects that display text which cannot be edited by the user. TCustomLabel introduces several new properties and methods to control the appearance of the text. TCustomLabel is not a descendant of TWinControl, so it does not have its own window and can’t receive direct input from the keyboard. To define an object that responds to direct keyboard input in addition to displaying text, use TCustomStaticText as a base class.

Do not create instances of TCustomLabel. To put a label on a form, use a TLabel object.


TCustomLabel properties

TCustomLabel	Alphabetically	Legend

In TCustomLabel

Alignment

AutoSize

FocusControl

Layout

ShowAccelChar

Transparent

WordWrap

Derived from TGraphicControl

Canvas

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomLabel properties

TCustomLabel	By object	Legend

Align

Alignment

AutoSize

BoundsRect

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

FocusControl

Height

Hint

Layout

Left

Name

Owner

Parent

ShowAccelChar

ShowHint

Tag

Top

Transparent

VCLComObject

Visible

Width

WindowProc

WordWrap


TCustomLabel::Alignment

TCustomLabel	See also 	Example

Controls the horizontal placement of the text within the label.

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

Set Alignment to specify how the text of the label is aligned within the ClientRect of the label control. Alignment can be one of the following values:

Value	Meaning

taLeftJustify	The text appears lined up along the left edge of the label.

taRightJustify	The text appears lined up along the right edge of the label.

taCenter	The text is horizontally centered in the label.

The effect of the Alignment property is more obvious if the WordWrap property is true and the label includes more than one line of text.


TCustomLabel::AutoSize

TCustomLabel	See also 	Example

Determines whether the size of the label automatically resizes to accommodate the text.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=1};

Description

Use AutoSize to make the label adjust its size automatically so the client area accommodates the height and width of the text. When AutoSize is false, the label is fixed in size. When AutoSize is true, the size of the label is readjusted whenever its text changes. The size of the label is also readjusted when the Font property changes.

When WordWrap is true, the width of the label is fixed. If AutoSize is also true, changes to the text cause the label to change in height. When AutoSize is true and WordWrap is false, the height of the label is determined by the font, and changes to the text cause the label to change in width.


TCustomLabel::FocusControl

TCustomLabel	See also	Example

Designates a windowed control associated with the label.

__property Controls::TWinControl* FocusControl = {read=FFocusControl, write=SetFocusControl};

Description

Set FocusControl to the windowed control that should receive focus when the user presses the accelerator key specified by the label. Specify an accelerator key by preceding a character in the label text with an ampersand (&) and setting the ShowAccelChar property to true.


TCustomLabel::Layout

TCustomLabel	See also

Specifies the vertical placement of the text within the label.

__property TTextLayout Layout = {read=FLayout, write=SetLayout, default=0};

Description

Set Layout to specify how the text of the label is placed within the ClientRect of the label control. Layout can be one of the following values:

Value	Meaning

tlTop	The text appears at the top of the label.

tlCenter	The text is vertically centered in the label.

tlBottom	The text appears along the bottom of the label.


TCustomLabel::ShowAccelChar

TCustomLabel	See also 	Example

Determines how an ampersand in the label text is displayed.

__property bool ShowAccelChar = {read=FShowAccelChar, write=SetShowAccelChar, default=1};

Description

Set ShowAccelChar to true to allow the label to display an underlined accelerator key value. When ShowAccelChar is true, any character preceded by an ampersand (&) appears underlined. If the FocusControl property is set, the windowed control specified by the FocusControl property receives input focus when the user types that underlined character. To display an ampersand when ShowAccelChar is true, use two ampersands (&&) to stand for the single ampersand that is displayed.

Set ShowAccelChar to false to display the label text with all ampersands appearing as ampersands. When ShowAccelChar is false, the value of the FocusControl property is not used.


TCustomLabel::Transparent

TCustomLabel	See also	Example

Specifies whether controls that sit below the label on a form can be seen through the label.

__property bool Transparent = {read=GetTransparent, write=SetTransparent, default=0};

Description

Set Transparent to true to prevent the label from obscuring other controls on the form. For example, if the label is used to add text to a graphic, set Transparent to true so that the label does not stand out as a separate object.

Writing text so that the background is transparent is slower than writing text when Transparent is false. If the label is not obscuring a complicated image, performance can be improved by setting the background color of the label to match the object beneath it and setting Transparent to false.


TCustomLabel::WordWrap

TCustomLabel	See also

Specifies whether the label text wraps when it is too long for the width of the label.

__property bool WordWrap = {read=FWordWrap, write=SetWordWrap, default=0};

Description

Set WordWrap to true to allow the label to display multiple line of text. When WordWrap is true, text that is too wide for the label control wraps at the right margin and continues in additional lines.

Set WordWrap to false to limit the label to a single line. When WordWrap is false, text that is too wide for the label appears truncated.


TCustomLabel methods

TCustomLabel	Alphabetically	Legend

In TCustomLabel

~TCustomLabel

AdjustBounds

DoDrawText

GetLabelText

Loaded

Notification

Paint

SetAutoSize

TCustomLabel

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomLabel methods

TCustomLabel	By object	Legend

~TCustomLabel

AdjustBounds

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DoDrawText

DoDrawText

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLabelText

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

Loaded

MethodAddress

MethodName

NewInstance

Notification

Paint

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetAutoSize

SetBounds

SetTextBuf

Show

TCustomLabel

Update


TCustomLabel::AdjustBounds

TCustomLabel	See also

Resizes the label when the text changes.

DYNAMIC void __fastcall AdjustBounds(void);

Description

When the text in the label or the font changes, AdjustBounds is implicitly called. It redraws the text in the client area, and then resizes the label if the AutoSize property is true.

When WordWrap is true, the width of the label is fixed. If AutoSize is also true, changes to the text cause the label to change in height. When AutoSize is true and WordWrap is false, the height of the label is determined by the font, and changes to the text cause the label to change in width.

Override AdjustBounds to make additional adjustments when the text changes.


TCustomLabel::TCustomLabel

TCustomLabel	See also

Creates and initializes an instance of TCustomLabel.

__fastcall virtual TCustomLabel(Classes::TComponent* AOwner);

Description

Call TCustomLabel to create an instance of TCustomLabel at runtime. Labels placed on forms at design time are created automatically.

After calling the parent object's constructor, TCustomLabel initializes the following properties:

•	AutoSize to true.

•	ShowAccelChar to true.

•	ControlStyle to [csOpaque, csReplicatable].

•	Width to 65 and Height to 17.


TCustomLabel::DoDrawText

TCustomLabel	See also

Renders the text in the client area.

DYNAMIC void __fastcall DoDrawText(Windows::TRect &Rect, Word Flags);

Description

When the label needs to draw itself, DoDrawText is implicitly called. DoDrawText uses the Windows API function, DrawText, to render the caption in the client area.

The first parameter, Rect, specifies the boundaries of the text within the client area. The second parameter, Flags, specifies how the text is aligned within those boundaries, how tab characters are handled, etc. See the Microsoft Windows API DrawText function for all the possible values of Flags.

Override DoDrawText to render text differently.


TCustomLabel::GetLabelText

TCustomLabel	See also

Returns the value of the Caption property.

virtual System::AnsiString __fastcall GetLabelText();

Description

Call GetLabelText to obtain the string that appears as the text of the label. GetLabelText is exposed as a protected method so that descendants can override this method to display text other than the value of the Caption property.


TCustomLabel::Loaded

TCustomLabel	See also

Adjusts the size of the label when it is first loaded. .

virtual void __fastcall Loaded(void);

Description

The protected loaded method is called immediately after a saved version of the label is loaded into memory. TCustomLabel overrides the parent class's method to adjust the size of the label to the text it contains if the AutoSize property is true.


TCustomLabel::Notification

TCustomLabel	See also

Responds to notifications when objects are about to be created or destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

Notification is called automatically when components are created or destroyed. After calling the parent class's method, Notification checks whether the windowed control specified by the FocusControl property is about to be destroyed. If the windowed control is going away, Notification sets the FocusControl property to NULL.


TCustomLabel::Paint

TCustomLabel	See also

Draws the image of the label.

virtual void __fastcall Paint(void);

Description

Paint is called automatically when the label receives a WM_PAINT message from its Parent. Paint writes the text returned by the GetLabelText method.


TCustomLabel::SetAutoSize

TCustomLabel	See also

Sets the AutoSize property.

virtual void __fastcall SetAutoSize(bool Value);

Description

SetAutoSize is the protected access method for the AutoSize property. It is exposed as a protected method so that descendants can override it to change the implementation of the AutoSize property.


TCustomLabel::~TCustomLabel

TCustomLabel

Frees the memory associated with the TCustomLabel object. Do not call ~TCustomLabel directly. Instead, use the delete keyword on the object, which causes ~TCustomLabel to be invoked automatically.

__fastcall virtual ~TCustomLabel(void) { }

Description

Do not call ~TCustomLabel directly. Instead, use the delete keyword on the object, which causes ~TCustomLabel to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


TCustomListBox

Hierarchy	Properties	Methods	Events	See also

TCustomListBox is the abstract base class for list box objects that are wrappers for Windows list box controls.

Unit

stdctrls

Description

TCustomListBox is an abstract class that encapsulates behavior common to all list box controls. List box objects are used to display a scrollable list from which users can select one or more items. Use a list box control to limit the user to selecting from a list of items. Items can be added at design time or at runtime.

As a wrapper for a list box TCustomListBox introduces methods for:

•	Displaying, sorting, selecting, manipulating, and querying items in the list.

•	Creating owner-draw style list boxes that can display graphical images such as icons and bitmaps.

•	Creating multiple-column and multiple-selection lists.

By default, TCustomListBox is a standard list box that displays items as text strings. These items are contained in a TStrings object, and the methods of the TStrings object are used to add, insert or delete a string. The following code demonstrates adding a new string to the list box:

MyListBox->Items->Add("New item");

Descendants of TCustomListBox inherit the basic functionality of TCustomListBox. Some descendants also have specialized behavior and can be linked to file, directory, drive, or database information. Use these list boxes to easily access and list this type of information.

A combo box is a list box with an edit control and an optional drop down style for the list. Use a combo box to allow users to type their selection into an edit box or to save space on a form by having the list drop down.

For lists of items that require a matrix or expandable tree-like structure use list views or tree views. These controls allow the grouping of items under column headings or in expandable and contractible rows.

Component Writers’ notes

For component writers wanting to create a customized list box objects, use TCustomListBox as a base class for deriving specialized list box objects.


TCustomListBox properties

TCustomListBox	Alphabetically	Legend

In TCustomListBox

BorderStyle

Canvas

Columns

ExtendedSelect

IntegralHeight

ItemHeight

ItemIndex

Items

MultiSelect

SelCount

Selected

Sorted

Style

TabWidth

TopIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomListBox properties

TCustomListBox	By object	Legend

Align

BorderStyle

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

ExtendedSelect

Handle

Height

HelpContext

Hint

IntegralHeight

ItemHeight

ItemIndex

Items

Left

MultiSelect

Name

Owner

Parent

ParentColor

ParentWindow

SelCount

Selected

ShowHint

Showing

Sorted

Style

TabOrder

TabStop

TabWidth

Tag

Top

TopIndex

VCLComObject

Visible

Width

WindowProc


TCustomListBox::BorderStyle

TCustomListBox	See also

Determines whether the list box has a border.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Use BorderStyle to change the appearance of the outer boundary of the list box control. A list box can have a single border or no visible border. The following table lists the possible values for BorderStyle:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border


TCustomListBox::Canvas

TCustomListBox	See also 	Example

Provides a drawing surface when implementing a handler for the OnDrawItem event of an owner-draw list box.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

Canvas is only useful for applications that control the drawing of list box items, that is, for owner-draw list boxes. Canvas is used to draw graphical images that can be used as items in a list box.

By default a TControlCanvas object is created for the Canvas property in the list box constructor. To create an owner-draw list box that uses a canvas, set the Style property accordingly.


TCustomListBox::Columns

TCustomListBox	See also

Specifies the number of columns, in a multi-column list box, that are visible without having to scroll.

__property int Columns = {read=FColumns, write=SetColumns, default=0};

Description

Use Columns to specify the number of columns, in a multi-column list box, that are visible without having to use the horizontal scrollbar.

Multi-column list boxes have a horizontal scrollbar that allows users to view multiple columns as they wrap. The default value for Columns is 0, meaning that the list box is not multi-column. That is, users can scroll only vertically and the list of items will not wrap.

For Columns values greater than 0, multiple columns accommodate the items as they wrap beyond the bottom of the list box. The Columns property specifies the number of columns that are visible without having to horizontally scroll the list box.

The width of each column depends upon both the Width property and the number of Columns.


TCustomListBox::ExtendedSelect

TCustomListBox	See also

Determines if the user can select a sequential range of items in the list box.

__property bool ExtendedSelect = {read=FExtendedSelect, write=SetExtendedSelect, default=1};

Description

ExtendedSelect works with the MultiSelect property. If ExtendedSelect is true and MultiSelect is true, the user can select an item then hold down the Shift key and select another and all the items in between the two selected items also become selected. If the user doesn’t hold down the Shift or Ctrl key while selecting a second item, the first selected item becomes unselected—in other words, the user must use the Ctrl key to select multiple noncontiguous items, or the Shift key to select a range of items.

If ExtendedSelect is false and MultiSelect is true, the user can select multiple items without using the Shift or Ctrl key, but they can’t select a range of items in one operation.

If MultiSelect is false, the setting of ExtendedSelect has no effect as the user will not be able to select more than one item at a time in the list box.


TCustomListBox::IntegralHeight

TCustomListBox	See also	Example

Determines whether the list box displays the partial items.

__property bool IntegralHeight = {read=FIntegralHeight, write=SetIntegralHeight, default=0};

Description

IntegralHeight controls the height of the list box itself.

When IntegralHeight is true, and the Style property is lsOwnerDrawFixed, the list box height will always be a multiple of the ItemHeight property value. In this case items will never be partially displayed.

If IntegralHeight is false, the list box height can be set to any value, but the last item may not be fully displayed.

If the Style property value of the list box is lbOwerDrawVariable, setting the IntegralHeight property to true has no effect.


TCustomListBox::ItemHeight

TCustomListBox	See also

Specifies the height in pixels of an item in an owner-draw list box.

__property int ItemHeight = {read=GetItemHeight, write=SetItemHeight, nodefault};

Description

Use ItemHeight to control the height of an item in a list box when the Style property is lsOwnerDrawFixed. The ItemHeight property can also affect the height of the list box itself. When the IntegralHeight property is true, the height of the list box is always an increment of the ItemHeight value.

If the Style property is lsStandard or lsOwnerDrawVariable, the value of ItemHeight is ignored.


TCustomListBox::ItemIndex

TCustomListBox	See also 	Example

Specifies the ordinal number of the selected item in the list box’s item list.

__property int ItemIndex = {read=GetItemIndex, write=SetItemIndex, nodefault};

Description

Use ItemIndex to select an item at runtime. Set the value of ItemIndex to the index of the item to be selected. The ItemIndex of the first item in the list box is 0. If no item is selected, the value is -1, which is the default value unless MultiSelect is true.

If the value of the MultiSelect property is true the user can select more than one item in the list box. In this case, the ItemIndex value is the index of the selected item that has focus. If MultiSelect is true, ItemIndex defaults to 0.


TCustomListBox::Items

TCustomListBox	See also 	Example

Contains the strings that appear in the list box.

__property Classes::TStrings* Items = {read=FItems, write=SetItems};

Description

Use Items to add, insert, delete and move items. By default the items in a list box are of type TStrings. Use this item type to access its methods or properties to manipulate the items in the list. For example, the following code adds the text in the edit box to the list box as an item:


TCustomListBox::MultiSelect

TCustomListBox	See also	Example

Determines whether the user can select more than one element at a time.

__property bool MultiSelect = {read=FMultiSelect, write=SetMultiSelect, default=0};

Description

Set MultiSelect to true to allow the user to select multiple items. If MultiSelect if false, multiple items cannot be selected in the list box at the same time.

MultiSelect allows users to select multiple non-sequential items. It does not allow users to select a range of items in one operation, as does the ExtendedSelect property.

When MultiSelect is true and multiple items are selected, the value of the ItemIndex property, which indicates the index of the Selected item, is the index of the selected item that has focus.


TCustomListBox::SelCount

TCustomListBox	See also

Indicates the number of items that are selected when multiple selections are allowed.

__property int SelCount = {read=GetSelCount, nodefault};

Description

SelCount is read-only. Use SelCount to find the number of selected items in the list box when the MultiSelect property is true.

When the MultiSelect property is false, SelCount is always -1::.


TCustomListBox::Selected

TCustomListBox	See also 	Example

Indicates whether a particular item is selected.

__property bool Selected[int Index] = {read=GetSelected, write=SetSelected};

Description

Use Selected to query the state of a particular item in the list box. If the item specified by the Index parameter is selected in the list box, the value of the Selected property is true. If the specified item is not selected, Selected is false.

The Index parameter is the item referenced by its position in the list box, with the first item having an Index value of 0.

An item is selected when the user highlights it. More than one item in the list box can be selected by setting the MultiSelect property to true. In this case, the Selected item is the one that has focus.


TCustomListBox::Sorted

TCustomListBox	See also 	Example

Specifies whether the items in a list box are arranged alphabetically.

__property bool Sorted = {read=FSorted, write=SetSorted, default=0};

Description

Use Sorted to sort the items by setting its value to true. If Sorted is false, the items are unsorted. When Sorted is true, items that are added or inserted are automatically into the list box in alphabetical order.


TCustomListBox::Style

TCustomListBox	See also	Example

Determines whether the list box is standard or owner-draw.

__property TListBoxStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

Use Style to specify whether a list box is a standard list box that displays text strings or an owner-draw list box that can display graphical images. By default, Style is lbStandard, meaning that the list box displays each item as a string.

Owner-draw list boxes let you display items in some nonstandard way. In this case, you must write the code. To create owner-draw list boxes, set the value of Style to lbOwnerDrawFixed or lbOwnerDrawVariable. The following table lists the values for the TListBoxStyle type of the Style property:

Value	Meaning

lbStandard	All items are strings, with each item the same height.

lbOwnerDrawFixed	Each item in the list box is the height specified by the ItemHeight property.

lbOwnerDrawVariable	Items in the list box can be of varying heights.

Owner-draw list boxes require more programming because the application needs information on how to render the image for each item in the list.

Each time an item is displayed in an lbOwnerDrawFixed list box, the OnDrawItem event occurs. The event handler for OnDrawItem draws the specified item. The ItemHeight property determines the height of each of the items.

Each time an item is displayed in an lbOwnerDrawVariable list box, two events occur. The first is the OnMeasureItem event. The code for the OnMeasureItem handler can set the height of each item. Then the OnDrawItem event occurs. The code for the OnDrawItem handler draws each item in the list box using the size specified by the OnMeasureItem handler.


TCustomListBox::TabWidth

TCustomListBox

Specifies the size of the tabs in the list box.

__property int TabWidth = {read=FTabWidth, write=SetTabWidth, default=0};

Description

Set TabWidth to control the number of dialog base units displayed for each tab character that appears in the strings of a list box.

If TabWidth is set to 0, which is the default setting, the tabs default to the width specified by Windows, which is two dialog base units.


TCustomListBox::TopIndex

TCustomListBox	See also 	Example

Specifies the index number of the item that appears at the top of the list box.

__property int TopIndex = {read=GetTopIndex, write=SetTopIndex, nodefault};

Description

Use TopIndex property to find or set the first item displayed at the top of the list box. TopIndex can be used, for example, to change the topmost item to a different item in the list.


TCustomListBox events

TCustomListBox	Alphabetically	Legend

In TCustomListBox

OnDrawItem

OnMeasureItem


TCustomListBox events

TCustomListBox	By object	Legend

OnDrawItem

OnMeasureItem


TCustomListBox::OnDrawItem

TCustomListBox	See also 	Example

Occurs when an item in an owner-draw list box needs to be redisplayed.

__property TDrawItemEvent OnDrawItem = {read=FOnDrawItem, write=FOnDrawItem};

Description

Use OnDrawItem to write a handler for drawing of the items in list boxes with the Style values lbOwnerDrawFixed or lbOwnerDrawVariable. OnDrawItem occurs whenever the list box needs to display an item. OnDrawItem occurs only for owner-draw list boxes.

OnDrawItem is of type TDrawItemEvent and passes four parameters to its handler describing the item to be drawn:

•	Control specifies a reference to the control containing the item.

•	Index specifies the index of the item in that control.

•	Rect specifies a rectangle in which to draw.

•	State specifies the state of the item (selected, focused, or disabled).

The size of the rectangle that contains the item is determined either by the ItemHeight property for fixed owner-draw list boxes or by the response to the OnMeasureItem event for variable owner-draw list boxes.

The Index parameter is the position of the item in the list box.

Rect is the area in the list box where the item is to be drawn. The Rect parameter automatically provides the proper location of the item within the control’s canvas.

State is the current state of the item in the list box. The TOwnerDrawState type defines the possible values for the State parameter. The following table lists these values:

Value	Meaning

odSelected	The item is selected.

odDisabled	The entire list box is disabled.

odFocused	The item currently has focus.


TCustomListBox::OnMeasureItem

TCustomListBox	See also 	Example

Occurs when the application needs to redisplay an item in a variable height owner-draw list box.

__property TMeasureItemEvent OnMeasureItem = {read=FOnMeasureItem, write=FOnMeasureItem};

Description

Use OnMeasureItem to write a handler to measure items to be drawn in a list box with a Style property value of lbOwnerDrawVariable.

OnMeasureItem is of type TMeasureItemEvent which contains three parameters describing the item to measure:

•	Control, specifying the control containing the item.

•	Index, specifying the index of the item in the control.

•	Height, specifying the height of the item.

The Index parameter identifies the position of the item in the list box.

The Height parameter should specify the height in pixels that the given item will occupy in the control. The Height parameter is a var parameter, which initially contains the default height of the item or the height of the item text in the control’s font. The handler can set Height to a value appropriate to the contents of the item, such as the height of a graphical image to be displayed within the item.

After the OnMeasureItem event occurs, the OnDrawItem event occurs, rendering the item with the measured size.


TCustomListBox methods

TCustomListBox	Alphabetically	Legend

In TCustomListBox

~TCustomListBox

Clear

CreateParams

CreateWnd

DeleteString

DestroyWnd

DragCanceled

DrawItem

GetItemData

ItemAtPos

ItemRect

MeasureItem

ResetContent

SetItemData

TCustomListBox

WndProc

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomListBox methods

TCustomListBox	By object	Legend

~TCustomListBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

CreateParams

CreateWnd

DefaultHandler

DeleteString

DestroyComponents

Destroying

DestroyWnd

DisableAlign

Dispatch

DragCanceled

DragDrop

Dragging

DrawItem

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetItemData

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

ItemAtPos

ItemRect

MeasureItem

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

ResetContent

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetItemData

SetTextBuf

Show

TCustomListBox

Update

UpdateControlState

WndProc


TCustomListBox::Clear

TCustomListBox	See also

Deletes all items from the list box.

void __fastcall Clear(void);

Description

Use Clear to delete all of the items in the list box at once. Although the items in a standard list box are of type TStrings, use the Clear method of the list box rather than calling the Clear method of the Items property.  This allows descendants of TCustomListBox to perform any other necessary clean-up in the Clear method, in addition to deleting the items from the Items property. Thus, applications should use

ListBox1->Clear();

rather than

ListBox1->Items->Clear();


TCustomListBox::TCustomListBox

TCustomListBox	See also

Instantiates a list box control.

__fastcall virtual TCustomListBox(Classes::TComponent* AOwner);

__fastcall TCustomListBox(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not call TCustomListBox. Instead, create TCustomListBox descendants such as TListBox or TDBListBox.

Pass a single Component as a parameter to provide the list box with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the list box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TCustomListBox allocates memory for a list box control, and calls the parent object's constructor. Then it:

•	Initializes values for its Width, Height and ItemHeight properties.

•	Sets ParentColor to false, and TabStop and ExtendedSelect to true.

•	Sets the ControlStyle for the list box.

•	Sets the BorderStyle property to bsSingle.

•	Creates a TControlCanvas object for the Canvas property.

•	Creates a TStrings type of object for the Items property.


TCustomListBox::TCustomListBox
TCustomListBox::CreateParams

TCustomListBox	See also

Initializes the window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams is used to pass information, in its Params parameter, to CreateWindowHandle when the list box control is created.

TCustomListBox overrides CreateParams to customize the representation of the window. It uses information from the list box Columns, ExtendedSelect, IntegralHeight, MultiSelect, Sorted and Style properties and sets WS_HSCROLL, WS_VSCROLL, LBS_HASSTRINGS and LBS_NOTIFY Windows styles for creation of the list box.

When overriding CreateParams, always call the parent class's method first to set the default values, then make any desired adjustments.


TCustomListBox::TCustomListBox
TCustomListBox::CreateWnd

TCustomListBox	See also

Creates a Windows control corresponding to the list box component.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd is called automatically when the list box must be displayed. CreateWnd calls the parent class's CreateWnd, which calls

•	CreateParams to initialize the window-creation parameters.

•	CreateWindowHandle to create the window handle for the control.

TCustomListBox::CreateWnd additionally sets up the list box position, tabs, items, and columns.


TCustomListBox::DeleteString

TCustomListBox

Deletes a string from the list box.

DYNAMIC void __fastcall DeleteString(int Index);

Description

DeleteString deletes the string specified by the Index parameter from list box control.


TCustomListBox::~TCustomListBox

TCustomListBox	See also

Destroys the instance of a list box control.

__fastcall virtual ~TCustomListBox(void);

Description

Do not call ~TCustomListBox directly in an application. Instead, an application should call delete, which causes ~TCustomListBox to be invoked automatically.


TCustomListBox::~TCustomListBox
TCustomListBox::DestroyWnd

TCustomListBox	See also

Saves the list box Items in a string list before calling the parent class's DestroyWnd.

virtual void __fastcall DestroyWnd(void);

Description

DestroyWnd saves the list box text string items, in the Items property, to internal storage in a TStringList object that it creates. Then it calls the parent class's DestroyWnd to destroy the windowed control’s window handle and free associated device contexts.


TCustomListBox::DragCanceled

TCustomListBox	See also

Sends a mouse message canceling the drag-and-drop operation.

DYNAMIC void __fastcall DragCanceled(void);

Description

DragCanceled is called in response to the cancellation of a drag-and-drop operation that had started. Users can cancel the operation by dropping the item over a component that does not accept the item, or by pressing Esc while dragging.

C++Builder calls the DragCanceled method before invoking the OnEndDrag event.


TCustomListBox::DrawItem

TCustomListBox	See also

Generates an OnDrawItem event.

virtual void __fastcall DrawItem(int Index, const Windows::TRect &Rect, TOwnerDrawState State);

Description

DrawItem is called whenever a visual aspect of an owner-draw list box changes. The list box calls DrawItem for each visible item in its list, passing the index of the item in the Index parameter.

By default, the DrawItem method for a list box calls any event handler attached to the component's OnDrawItem event. If there is no handler attached, DrawItem fills the rectangle passed in Rect and draws any text associated with the indexed item. The default drawing ignores the State parameter, although State is passed along to attached event handlers.


TCustomListBox::GetItemData

TCustomListBox	See also

Returns a 32-bit value associated with the specified item in a list box.

DYNAMIC int __fastcall GetItemData(int Index);

Description

Use GetItemData to retrieve the data associated with a particular item in a list box. This value can be displayed as that list box item, or can be a value (such as a pointer) associated with the list box item.


TCustomListBox::ItemAtPos

TCustomListBox	See also 	Example

Returns the index of the list box item indicated by the coordinates of a point on the control.

int __fastcall ItemAtPos(const tagPOINT &Pos, bool Existing);

Description

Use ItemAtPos to detect if an item exists at a particular point in the control.

The Pos parameter is the point in the control in window coordinates. If Pos is beyond the last item in the list box, the value of the Existing variable determines the returned value. If Existing is set to true, ItemAtPos returns -1, indicating that no item exists at that point. If Existing is set to false, ItemAtPos returns the index of the last item in the list box plus one.


TCustomListBox::ItemRect

TCustomListBox	See also 	Example

Returns the rectangle that surrounds the item specified in the Item parameter.

Windows::TRect __fastcall ItemRect(int Index);

Description

Use ItemRect to get the coordinates of a particular item in the list box. For example, ItemRect is used internally by the ItemAtPos method.

The Item parameter is the ItemIndex of the item whose position is queried.


TCustomListBox::MeasureItem

TCustomListBox	See also

Generates an OnMeasureItem event.

virtual void __fastcall MeasureItem(int Index, int &Height);

Description

MeasureItem is called whenever a visual aspect of a variable owner-draw list box, with the csOwnerDrawVariable Style set, changes.

Before drawing its items , a variable owner-draw list box calls MeasureItem once for each visible item, passing the index of the item to measure, and the default height of the item. Since Height is a var parameter, MeasureItem can increase or reduce the height of each item as needed.

By default, the MeasureItem method does nothing except call any event handler attached to the OnMeasureItem event. Override MeasureItem to change or add functionality to the default behavior.


TCustomListBox::ResetContent

TCustomListBox	See also

Removes all of the items from a list box.

DYNAMIC void __fastcall ResetContent(void);

Description

ResetContent is used to remove the items from the list box. ResetContent is used, for example, by the Clear method.


TCustomListBox::SetItemData

TCustomListBox	See also

Sets the 32-bit value associated with the specified item in a list box.

DYNAMIC void __fastcall SetItemData(int Index, int AData);

Description

Use SetItemData to set the data associated with a particular item in a list box. This value can be displayed as that list box item, or it can be a value (such as a pointer) represented by the list box item.


TCustomListBox::WndProc

TCustomListBox	See also

Handles Windows messages.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc overrides the parent class's WndProc to provide specialized responses to messages that allows the list box to handle auto drag mode itself. Then it calls the parent class's WndProc to handle all other messages.

When overriding the WndProc method, be sure to call the parent class's WndProc at the end to dispatch any other messages.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomListView

Hierarchy	Properties	Methods	Events	See also

TCustomListView is the abstract base type for all list view components, including TListView.

Unit

comctrls

Description

Use TCustomListView as a base class when defining a control that displays a list of items. TCustomListView allows a list of items to be displayed in columns with column headers and sub-items, or vertically or horizontally, with small or large icons.

Do not create instances of TCustomListView. To put a list view on a form, use a descendant of TCustomListView, such as TListView.


TCustomListView properties

TCustomListView	Alphabetically	Legend

In TCustomListView

AllocBy

BorderStyle

BoundingRect

Checkboxes

Column

ColumnClick

Columns

DropTarget

GridLines

HideSelection

HotTrack

IconOptions

ItemFocused

Items

LargeImages

MultiSelect

ReadOnly

RowSelect

SelCount

Selected

ShowColumnHeaders

SmallImages

SortType

StateImages

TopItem

ViewOrigin

ViewStyle

VisibleRowCount

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomListView properties

TCustomListView	By object	Legend

Align

AllocBy

BorderStyle

BoundingRect

BoundsRect

Brush

Checkboxes

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Column

ColumnClick

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DropTarget

Enabled

GridLines

Handle

Height

HelpContext

HideSelection

Hint

HotTrack

IconOptions

ItemFocused

Items

LargeImages

Left

MultiSelect

Name

Owner

Parent

ParentWindow

ReadOnly

RowSelect

SelCount

Selected

ShowColumnHeaders

ShowHint

Showing

SmallImages

SortType

StateImages

TabOrder

TabStop

Tag

Top

TopItem

VCLComObject

ViewOrigin

ViewStyle

Visible

VisibleRowCount

Width

WindowProc


TCustomListView::AllocBy

TCustomListView	See also

Indicates the number of items the list view can store in memory.

__property int AllocBy = {read=FAllocBy, write=SetAllocBy, default=0};

Description

Set AllocBy to the total number of items in the list before adding a large number of items to the list view. AllocBy allows the list view to allocate the memory for items in a single block at once rather than bit by bit as items are added.


TCustomListView::BorderStyle

TCustomListView	See also

Determines whether the list view displays a single line border.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Use BorderStyle to affect the sharpness with which the list view control stands out on a form. BorderStyle can have a value of either bsSingle or bsNone. If BorderSyle is bsSingle, the list view is drawn with a single-line border. If BorderStyle is bsNone, there will be no border.

Note:	BorderStyle interacts with the Ctl3D property to create different visual effects. Try combining different combinations of the two properties to get the desired look.


TCustomListView::BoundingRect

TCustomListView	See also

Denotes the bounding rectangle for the items in the list view.

__property Windows::TRect BoundingRect = {read=GetBoundingRect};

Description

Read BoundingRect to obtain the screen coordinates of a rectangle that encloses all the items in the list view. BoundingRect allows an application to adjust the size of the control to fit the items or to determine whether the mouse is over any of the list items.

Note:	To use BoundingRect, the list view’s ViewStyle property must be either vsIcon or vsSmallIcon.


TCustomListView::CheckBoxes

TCustomListView	See also

Specifies whether check boxes appear next to the items in the list view.

__property bool Checkboxes = {read=FCheckboxes, write=SetCheckboxes, default=0};

Description

Set CheckBoxes to true to make check boxes appear next to the list items when ViewStyle is vsList or vsReport. Each line in the list displays a single check box.


TCustomListView::Column

TCustomListView	See also	Example

Describes the column specified by the Index parameter.

__property TListColumn* Column[int Index] = {read=GetColumnFromIndex};

Description

Read Column to access the TListColumn object that describes the column attributes of a column in a report style list view. The Index parameter is the index of the column in the Columns property array.

Note:	Column is only relevant when the value of the ViewStyle property is vsReport.


TCustomListView::ColumnClick

TCustomListView	See also

Determines whether the column header behaves like a button.

__property TLVColumnClickEvent OnColumnClick = {read=FOnColumnClick, write=FOnColumnClick};

Description

Use ColumnClick to specify whether the OnColumnClick event should occur when the user clicks on the column header. When ColumnClick is true, the OnColumnClick occurs when the column header is clicked with the mouse. When ColumnClick is false, the OnColumnClick event never occurs.

Note:	For column clicks to work, the column headers must be displayed. To display the headers, set the ShowColumnHeaders property to true and the ViewStyle property to vsReport.


TCustomListView::Columns

TCustomListView	See also 	Example

Describes the properties of the columns in the list view.

__property TListColumns* Columns = {read=FListColumns, write=SetListColumns};

Description

Use Columns to add or delete columns in the list view, or to edit their display properties. When setting Columns at design time a ListView Columns Editor dialog appears. This dialog allows columns to be added or deleted, and the display properties of individual columns to be changed. At runtime, use the Caption, Alignment, and Width properties of the TListColumn objects accessed by the Columns property to change the appearance of the column headers.

Note:	To display the columns, set the ViewStyle property to vsReport and the ShowColumnHeaders property to true.


TCustomListView::DropTarget

TCustomListView	See also

Specifies which item in the list is the target of a drag and drop operation.

__property TListItem* DropTarget = {read=GetDropTarget, write=SetDropTarget};

Description

Read DropTarget to determine whether an item in the list is the target of a drag and drop operation. Set DropTarget to change whether a particular item in the list can be the drop target of a dragged item.

Note:	DropTarget only indicates the list item that appears to the user as a drop target. The application must still implement the drag-and-drop behavior for the item.


TCustomListView::GridLines

TCustomListView	See also

Determines whether lines are drawn separating items in the list.

__property bool GridLines = {read=FGridLines, write=SetGridLines, default=0};

Description

Set GridLines to true to add lines that separate the items in the list view. The value of GridLines is ignored unless ViewStyle is vsList or vsReport.


TCustomListView::HideSelection

TCustomListView	See also

Determines whether the list view gives a visual indication of which item is selected when focus shifts to another control.

__property bool HideSelection = {read=FHideSelection, write=SetHideSelection, default=1};

Description

Set HideSelection to false to provide visual feedback of the selected item in the list even when the list view does not have focus. Set HideSelection to true to show the selection only when the list view has focus. HideSelection does not affect the actual value of the selection, only the visual indication. Always setting HideSelection to false can make forms with many list views look too busy.


TCustomListView::HotTrack

TCustomListView	See also

Specifies whether list items are highlighted when the mouse passes over them.

__property bool HotTrack = {read=FHotTrack, write=SetHotTrack, default=0};

Description

Set HotTrack to true to have the list view provide visual feedback about which item is under the mouse. When HotTrack is false, the list view items do not change color when the mouse passes over them.


TCustomListView::IconOptions

TCustomListView	See also

Determines how icons displayed in the list view are arranged.

__property TIconOptions* IconOptions = {read=FIconOptions, write=SetIconOptions};

Description

Set the properties of the TIconOptions object that is the value of IconOptions to specify how the icons in the list view should be arranged. The ViewStyle of the list view must be set to either vsIcon or vsSmallIcons for these options to affect the control.


TCustomListView::ItemFocused

TCustomListView	See also

Indicates which item, if any, has focus.

__property TListItem* ItemFocused = {read=GetFocused, write=SetFocused};

Description

Read ItemFocused to determine which item, if any, can be edited by the user. Set ItemFocused to set focus to an item in the list. When an item has focus, it appears surrounded by a standard focus rectangle. If no item has focus, ItemFocused returns NULL. Only one item can have focus at a time.


TCustomListView::Items

TCustomListView	See also	Example

Contains the list of items displayed by the list view.

__property TListItems* Items = {read=FListItems, write=SetItems};

Description

Use Items to directly access the TListItem objects that represent the items in the list. Setting this property at design time brings up the ListView Items Editor. Use this dialog to add or delete items or subitems, and to edit their display properties. At runtime, use each item's Caption, ImageIndex, and StateIndex properties to change the appearance of the list items.


TCustomListView::LargeImages

TCustomListView	See also 	Example

Provides a list of icon images to display for each item in the list when ViewStyle is vsIcon.

__property Controls::TImageList* LargeImages = {read=FLargeImages, write=SetLargeImages};

Description

Set LargeImages to specify the bitmaps that should be displayed next to items in the list when ViewStyle is vsIcon. Each item in the Items list can be associated with a bitmap in this image list by setting its ImageIndex property.


TCustomListView::MultiSelect

TCustomListView	See also

Determines whether the user can select more than one list item at a time.

__property bool MultiSelect = {read=FMultiSelect, write=SetMultiSelect, default=0};

Description

Set MultiSelect to specify whether users can multiselect items in the list. If MultiSelect is true, the user can select multiple items. If MultiSelect if false, only one item can be selected at a time.


TCustomListView::ReadOnly

TCustomListView	See also

Determines whether the user can change the contents of the control.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, default=0};

Description

Use ReadOnly to determine whether the list view can be used to enter data. If ReadOnly is true, the list view displays values that the user can’t edit. If ReadOnly is false, the user can modify the contents. If ReadOnly is false, the OnEditing and OnEdited events occur when the user begins and finishes editing the list item, respectively.


TCustomListView::RowSelect

TCustomListView	See also

Determines whether an entire row in the list view can be selected.

__property bool RowSelect = {read=FRowSelect, write=SetRowSelect, default=0};

Description

Set RowSelect to true to allow entire rows to be selected when the ViewStyle property is vsReport. To allow multiple rows to be selected, use the MultiSelect property.


TCustomListView::SelCount

TCustomListView	See also

Specifies the number of selected items in the list view.

__property int SelCount = {read=GetSelCount, nodefault};

Description

Read SelCount to determine the number of items that are currently selected. When SelCount is 1, use the Selected property to access the selected item. To locate the selected items when SelCount is greater than one, check the Selected property of the list items, beginning with the item specified by the Selected property.

Note:	SelCount can only exceed 1 if the MultiSelect property is true.


TCustomListView::Selected

TCustomListView	See also 	Example

Indicates the first selected item in the list view.

__property TListItem* Selected = {read=GetSelection, write=SetSelection};

Description

Read Selected to access the properties of the first selected item in the list. If SelCount is 0, Selected is NULL. If SelCount is greater than 1, subsequent selected items can be located by checking the Selected property of the items found using the GetNextItem method.

Set the Selected property to select an item in the list. If MultiSelect is true, setting Selected adds an item to the selection. If MultiSelect is false, setting Selected changes the selection. Setting Selected to NULL deselects all items in the list.

When an item is selected, the OnChanging and OnChange events are generated.


TCustomListView::ShowColumnHeaders

TCustomListView	See also	Example

Determines whether the column headers are displayed.

__property bool ShowColumnHeaders = {read=FShowColumnHeaders, write=SetColumnHeaders, default=1};

Description

Set ShowColumnHeaders to specify whether the columns in the list view should display column headers. A column header is a panel with a caption that identifies the category of items in the column of the list view. Headers are useful for labeling columns of subitems that provide additional information in a list view. Use the Columns property to create or add headers.

Note:	To use columns in a list view, the ViewStyle property must be set to vsReport.


TCustomListView::SmallImages

TCustomListView	See also	Example

Provides a list of icon images to display for each item in the list when ViewStyle is not vsIcon.

__property Controls::TImageList* SmallImages = {read=FSmallImages, write=SetSmallImages};

Description

Set SmallImages to specify the icons that should be displayed next to items in the list when ViewStyle is vsSmallIcon, vsList, or vsReport. Each item in the Items list can be associated with an icon in this image list by setting its ImageIndex property.


TCustomListView::SortType

TCustomListView 	See also

Determines if and how the items in the list are automatically sorted.

__property TSortType SortType = {read=FSortType, write=SetSortType, default=0};

Description

Set SortType to specify the order of items in the list. If SortType is not stNone, the list items in the Items property are automatically sorted. Once a list view is sorted, the original order is lost. That is, setting the SortType back to stNone will not restore the original order of items. These are the possible values:

Value	Meaning

stNone	No sorting is done.

stData	Items are sorted based on the Data property of the TListItem objects. An OnCompare event handler must be provided to compare Data values.

stText	Items are sorted based on the Caption property of the TListItem objects.

stBoth	Items are sorted based on both the Data and Caption properties of the TListItem objects. The Data values are ignored unless an OnCompare event handler is provided.


TCustomListView::StateImages

TCustomListView	See also

Provides a list of additional icon images to display next to each item in the list view.

__property Controls::TImageList* StateImages = {read=FStateImages, write=SetStateImages};

Description

Set StateImages to specify the icons that should be displayed next to items in the list. Each item in the Items list can be associated with an icon in this image list by setting its StateIndex property.


TCustomListView::TopItem

TCustomListView	See also	Example

Indicates the topmost visible item in the list view.

__property TListItem* TopItem = {read=GetTopItem};

Description

Read TopItem to determine the first item in the list view that the user can see. TopItem reflects how far the list view has been scrolled.

TopItem is only implemented when ViewStyle is vsReport or vsList. For vsIcon and vsSmallIcon view styles, use the ViewOrigin property to determine the scroll position.


TCustomListView::ViewOrigin

TCustomListView	See also

Designates the coordinates of the upper left corner of the list, relative to the visible area of the list view control.

__property tagPOINT ViewOrigin = {read=GetViewOrigin};

Description

Read ViewOrigin to determine the logical origin of the list image. When the list view is not scrolled, ViewOrigin is (0,0). Otherwise, use the x coordinate to determine the number of pixels the view is scrolled horizontally, and the y coordinate to determine the number of pixels the view is scrolled vertically.

ViewOrigin is only implemented when ViewStyle is vsIcon or vsSmallIcon. For vsReport or vsList, use the TopItem property instead.


TCustomListView::ViewStyle

TCustomListView	See also	Example

Determines how the list items are displayed.

__property TViewStyle ViewStyle = {read=FViewStyle, write=SetViewStyle, default=0};

Description

Set ViewStyle to control the visual display of items in a list view. The items can be displayed as a set of movable icons, or as columns of text. These are the possible values:

Value	Meaning

vsIcon	Each item appears as a full-sized icon with a label below it. The user can drag the items to any location in the list view window.

vsSmallIcon	Each item appears as a small icon with the label to the right of it. The user can drag the items to any location.

vsList	Each item appears as a small icon with a label to the right of it. Items are arranged in columns and cannot be dragged by the user.

vsReport	Each item appears on its own line with information arranged in columns. The leftmost column contains the small icon and label, and subsequent columns contain subitems as specified by the application. Unless ShowColumnHeaders is false, each column has a header.


TCustomListView::VisibleRowCount

TCustomListView	See also

Indicates number of items that can fit vertically in the visible area of a list view.

__property int VisibleRowCount = {read=GetVisibleRowCount, nodefault};

Description

Read VisibleRowCount to determine the number of items from a single column that can appear in the visible area of a list view when the ViewStyle is either vsList or vsReport. Only fully visible items are counted. If VisibleRowCount is less than the total number of items in a column, use the TopItem property to determine if the list view is scrolled.


TCustomListView events

TCustomListView	Alphabetically	Legend

In TCustomListView

OnChange

OnChanging

OnColumnClick

OnCompare

OnDeletion

OnEdited

OnEditing

OnInsert


TCustomListView events

TCustomListView	By object	Legend

OnChange

OnChanging

OnColumnClick

OnCompare

OnDeletion

OnEdited

OnEditing

OnInsert


TCustomListView::OnChange

TCustomListView	See also

Occurs immediately after an item in the list changes.

__property TLVChangeEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to respond to changes in the list items. OnChange allows a response once the list has been successfully changed.

The Item parameter is the list item that just changed. The Change parameter indicates the type of change that just occurred. Change is ctText if the Caption property of the item changed. Change is ctImage if the ImageIndex property of the item changed or the appropriate image list changed in the list view. Change is ctState if the Cut, Focused, or Selected property of the item changed.


TCustomListView::OnChanging

TCustomListView	See also

Occurs when an item in the list is about to change.

__property TLVChangingEvent OnChanging = {read=FOnChanging, write=FOnChanging};

Description

Write an OnChanging event handler to conditionally block changes to an item in the list. Set the AllowChange parameter to false to prevent the change from taking place. The Item parameter is the list item that is about to change. The Change parameter indicates the type of change that is about to happen.

Change is ctText if the Caption property of the item is about to change. Change is ctImage if the ImageIndex property of the item is about to change. Change is ctState if the Cut, Focused, or Selected property of the item is about to change.


TCustomListView::OnColumnClick

TCustomListView	See also

Occurs when the user clicks on a column header in a list view.

__property TLVColumnClickEvent OnColumnClick = {read=FOnColumnClick, write=FOnColumnClick};

Description

Write an OnColumnClick event handler to respond to mouse clicks made in the column header when ViewStyle is vsReport. The Column parameter is the TListColumn object from the Columns property that describes the column that was clicked.

OnColumnClick only occurs when ViewStyle is vsReport, ShowColumnHeaders is true, and ColumnClick is true.


TCustomListView::OnCompare

TCustomListView	See also

Occurs to when two items need to be compared during a sort of the list.

__property TLVCompareEvent OnCompare = {read=FOnCompare, write=FOnCompare};

Description

Write an OnCompare event handler to implement a sort order for the list. An OnCompare event handler is called when the SortType property is stData or stBoth, when the AlphaSort method is called, or when the CustomSort method is called without a SortProc parameter.

The OnCompare event handler compares the list items passed as the Item1 and Item2 parameters. If Item1 is the same as Item2 in the sort order, set the Compare parameter to 0. If Item1 is less than Item2, set the Compare parameter to a value less than 0. If Item1 is greater than Item2, set the Compare parameter to a value greater than 0.

The Data parameter is 0 when the event handler is called to maintain the sort order of a list view with a SortType of stData or stBoth. Similarly, when OnCompare occurs in response to the AlphaSort method, the Data parameter is 0. When OnCompare occurs in response to the CustomSort method, the Data parameter is the value of the LParam parameter of CustomSort.


TCustomListView::OnDeletion

TCustomListView	See also

Occurs when an item in the list view is about to be deleted.

__property TLVDeletedEvent OnDeletion = {read=FOnDeletion, write=FOnDeletion};

Description

Write an OnDeletion event handler to respond when an item in the list is about to be deleted. The Item parameter is the TListItem object from the Items property that is about to be deleted.


TCustomListView::OnEdited

TCustomListView	See also

Occurs immediately after the user edits an item’s Caption property.

__property TLVEditedEvent OnEdited = {read=FOnEdited, write=FOnEdited};

Description

Write an OnEdited event to take specific action when a user has finished editing the text of a list item. An OnEdited event handler can respond to the value the user typed, or change the value that is assigned to the list item’s Caption property. For example, if an OnEdited event handler can check the validity of the string typed by the user, and only allow the Caption property to be changed if the new value is valid.

The Item parameter is the list item that was just edited. The S parameter is the new value the user typed for the item’s Caption property. Change the value of S to override the value the user typed. When OnEdited occurs, the item’s Caption property has not yet been changed, so S can still be compared to the original value of Caption.

This event can occur only if ReadOnly is set to false.


TCustomListView::OnEditing

TCustomListView	See also

Occurs when the user starts to edit a list item’s Caption property.

__property TLVEditingEvent OnEditing = {read=FOnEditing, write=FOnEditing};

Description

Write an OnEditing event handler to take specific action just before a user edits a list item’s Caption property. To prevent the user from editing the item specified by the ListItem parameter, set the AllowEdit parameter to false.

This event can occur only if the ReadOnly property is set to false.


TCustomListView::OnInsert

TCustomListView	See also

Occurs immediately after a new item is inserted into the list view.

__property TLVDeletedEvent OnInsert = {read=FOnInsert, write=FOnInsert};

Description

Write an OnInsert event handler to respond when an item has just been added to the list. The Item parameter is the TListItem object from that was added to the Items property.


TCustomListView methods

TCustomListView	Alphabetically	Legend

In TCustomListView

~TCustomListView

AlphaSort

Arrange

CanChange

CanEdit

Change

ColClick

ColumnsShowing

CreateListItem

CreateParams

CreateWnd

CustomSort

Delete

DestroyWnd

DoEndDrag

DoStartDrag

Edit

FindCaption

FindData

GetDragImages

GetItemAt

GetItemIndex

GetNearestItem

GetNextItem

GetSearchString

InsertItem

IsEditing

Notification

Scroll

StringWidth

TCustomListView

UpdateColumn

UpdateColumns

UpdateItems

WndProc

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomListView methods

TCustomListView	By object	Legend

~TCustomListView

AlphaSort

Arrange

Assign

BeginDrag

BringToFront

Broadcast

CanChange

CanEdit

CanFocus

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ColClick

ColumnsShowing

ContainsControl

ControlAtPos

CreateListItem

CreateParams

CreateWnd

CustomSort

DefaultHandler

Delete

DestroyComponents

Destroying

DestroyWnd

DisableAlign

Dispatch

DoEndDrag

DoStartDrag

DragDrop

Dragging

Edit

EnableAlign

EndDrag

FieldAddress

FindCaption

FindComponent

FindData

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetDragImages

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetItemAt

GetItemIndex

GetNamePath

GetNearestItem

GetNextItem

GetParentComponent

GetSearchString

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InsertItem

InstanceSize

Invalidate

IsEditing

MethodAddress

MethodName

NewInstance

Notification

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

Scroll

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

StringWidth

TCustomListView

Update

UpdateColumn

UpdateColumns

UpdateControlState

UpdateItems

WndProc


TCustomListView::AlphaSort

TCustomListView	See also

Sorts the items in the list view.

bool __fastcall AlphaSort(void);

Description

Call AlphaSort to sort the items in the manner maintained automatically by when the SortType property is not stNone. If an OnCompare event handler is assigned, AlphaSort uses that event handler to define the sort order. Otherwise, AlphaSort sorts all the list items alphabetically in ascending order. If successful, the method returns true.


TCustomListView::Arrange

TCustomListView 	See also

Arranges icons in a list view that has a ViewStyle of vslcon or vsSmallIcon.

void __fastcall Arrange(TListArrangement Code);

Description

Call Arrange to clean up the arrangement of the icons when the ViewStyle property is vslcon or vsSmallIcon. The Code parameter specifies how to arrange the icons. These are the possible values for the Code parameter:

Value	Meaning

arAlignBottom	Aligns items along the bottom edge of the list view.

arAlignLeft	Aligns items along the left edge of the window.

arAlignRight	Aligns items along the right edge of the window.

arAlignTop	Aligns items along the top edge of the window.

arDefault	Aligns items according to the style associated with the list view when the window was created. For TCustomListView, this is aligned along the top.

arSnapToGrid	Snaps all icons to the nearest grid position.


TCustomListView::CanChange

TCustomListView	See also

Specifies whether the properties of a list item can be changed.

DYNAMIC bool __fastcall CanChange(TListItem* Item, int Change);

Description

CanChange is called automatically when an attempt is made to change the item specified by the Item parameter. The Change parameter is a Windows-defined constant that specifies the type of change that was attempted. CanChange generates an OnChanging event to determine whether the change should be permitted. CanChange returns true if the change can proceed. CanChange returns false if the change should be blocked. CanChange always returns true if there is no OnChanging event handler.

Override CanChange to add additional logic to determine whether a change should proceed or to block the OnChanging event.


TCustomListView::CanEdit

TCustomListView	See also

Specifies whether the text of a list item can be changed by the user.

DYNAMIC bool __fastcall CanEdit(TListItem* Item);

Description

CanEdit is called automatically when the user attempts to edit the text of the list item specified by the Item parameter. CanEdit generates an OnEditing event to determine whether to allow the user to edit the item. CanEdit returns true if the user can proceed. CanEdit returns false if the user should be blocked from editing the item. CanEdit always returns true if there is no OnEditing event handler.

Override CanEdit to add additional logic to determine whether an item can be edited or to block the OnEditing event.


TCustomListView::Change

TCustomListView	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(TListItem* Item, int Change);

Description

Change is called automatically after the properties of the item specified by the Item parameter change. The Change parameter is a Windows-defined constant that specifies the type of change that occurred.

Override Change to perform other actions when the list items change or to block the OnChange event.


TCustomListView::ColClick

TCustomListView	See also

Generates an OnColumnClick event.

DYNAMIC void __fastcall ColClick(TListColumn* Column);

Description

ColClick is called automatically when the user clicks on a column header if the ColumnClick and ShowColumnHeaders properties are true and the ViewStyle property is vsReport. Override ColClick to take additional action when the user clicks on a column header or to conditionally block the OnColumnClick event.


TCustomListView::ColumnsShowing

TCustomListView	See also

Indicates whether the ViewStyle property is vsReport.

bool __fastcall ColumnsShowing(void);

Description

Call ColumnsShowing to determine whether the list view displays its items in columns. ColumnsShowing returns true if the value of ViewStyle is vsReport, false otherwise.


TCustomListView::TCustomListView

TCustomListView	See also	Example

Creates and initializes an instance of TCustomListView.

__fastcall virtual TCustomListView(Classes::TComponent* AOwner);

__fastcall TCustomListView(HWND ParentWindow) : Controls::TWinControl(

ParentWindow) { }

Description

Do not call TCustomListBox. To put a list view on a form, use a descendant of TCustomListView, such as TListView.

TCustomListView instantiates a list view at runtime. List view controls placed on forms at design time are created automatically.

After calling the parent object's constructor, TCustomListView initializes the following properties:

•	BorderStyle to bsSingle

•	ColumnClick and ShowColumnHeaders to true

•	ControlStyle to [csClickEvents, csDoubleClick, csDisplayDragImage, csSetCaption, csReflector]

•	Height to 150 and Width to 250

•	HideSelection to true

•	TabStop to true

•	ViewStyle to vsIcon


TCustomListView::TCustomListView
TCustomListView::CreateListItem

TCustomListView	See also

Creates a list item for the collection specified by the Items property.

virtual TListItem* __fastcall CreateListItem(void);

Description

Call CreateListItem to create a TListItem object that will be added to the Items collection. CreateListItem creates the list item but does not insert it into the collection.


TCustomListView::TCustomListView
TCustomListView::CreateParams

TCustomListView	See also

Initializes the window-creation parameter record.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams is called automatically to initialize the window-creation parameters when the list view needs to create its window. CreateParams overrides the parent class's method to specify a list view window that implements the property settings of the list view control.

When overriding the CreateParams method, be sure to call the parent class's method before changing any of the values in the Params parameter.


TCustomListView::TCustomListView
TCustomListView::CreateWnd

TCustomListView	See also

Creates the window used by the list view.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd creates the list view’s window, based on the parameter values provided by the CreateParams method. CreateWnd then sends messages to the newly created window so it reflects the current property settings of the list view object.


TCustomListView::CustomSort

TCustomListView	See also 	Example

Sorts the items in the list using the specified ordering function.

bool __fastcall CustomSort(PFNLVCOMPARE SortProc, int lParam);

Description

Call CustomSort to sort the items in the list using the ordering function defined by the SortProc parameter. The SortProc parameter specifies an ordering function that compares the list items passed as lParam1 and lParam2. The ordering function returns an integer that indicates whether lParam1 is the same as lParam2 (return value is 0), lParam1 is greater than lParam2 (return value is greater than 0), or lParam1 is less than lParam2 (return value is less than 0). The lParam parameter of CustomSort is an optional value that is passed as the third parameter to the ordering function.

If the SortProc parameter is NULL, CustomSort compares the list items by generating an OnCompare event. This allows the OnCompare event handler to provide different ordering criteria (such as ascending vs. descending order), based on the value of the lParam parameter.

If the ordering function is not provided and there is no OnCompare event handler, CustomSort sorts items alphabetically by their Caption values.

CustomSort returns true if the list is successfully sorted.


TCustomListView::Delete

TCustomListView	See also

Removes an item from the list view and frees the associated memory.

DYNAMIC void __fastcall Delete(TListItem* Item);

Description

Call Delete to remove an item from the list view. Delete generates an OnDeletion event before freeing the list item.


TCustomListView::~TCustomListView

TCustomListView	See also

Destroys an instance of TCustomListView.

__fastcall virtual ~TCustomListView(void);

Description

Do not call ~TCustomListView directly. Instead, call Delete, which verifies that the list item is not already freed before calling ~TCustomListView.


TCustomListView::~TCustomListView
TCustomListView::DestroyWnd

TCustomListView	See also

Destroys the window referenced by the list view’s window handle.

virtual void __fastcall DestroyWnd(void);

Description

Before the window is destroyed, DestroyWnd saves a copy of the list view in internal storage. The parent class's method then frees any device contexts, and destroys the window.


TCustomListView::DoEndDrag

TCustomListView	See also

Generates an OnEndDrag event.

DYNAMIC void __fastcall DoEndDrag(System::TObject* Target, int X, int Y);

Description

After generating an OnEndDrag event, DoEndDrag clears the internal variables used to track which item is the drop target.


TCustomListView::DoStartDrag

TCustomListView	See also

Generates an OnStartDrag event and begins tracking the drop target.

DYNAMIC void __fastcall DoStartDrag(Controls::TDragObject* &DragObject);

Description

DoStartDrag is called automatically when the user starts dragging a list item with the mouse. After generating an OnStartDrag event, DoStartDrag generates a drag image and begins calculating drop target positions.


TCustomListView::Edit

TCustomListView	See also

Sets the Caption property of a list item after it has been edited by the user.

DYNAMIC void __fastcall Edit(const tagLVITEMA &Item);

Description

Edit is called automatically when the user finishes editing the label of a list item. Edit obtains the newly edited value from the Windows list item and generates an OnEdited event. After allowing the OnEdited event handler to change the value supplied by the user, Edit sets the Caption property of the list item.


TCustomListView::FindCaption

TCustomListView	See also

Returns a list view item, if any, with the specified caption.

TListItem* __fastcall FindCaption(int StartIndex, System::AnsiString Value, bool Partial, bool Inclusive, bool Wrap);

Description

Call FindCaption to search for a list view item labeled by the string specified as the Value parameter. If the Inclusive parameter is true, the list item specified by StartIndex is the first item checked. Otherwise, the search starts on the next item. If the Wrap parameter is true, the search continues at the top of the list if a match has not been found before reaching the bottom. FindCaption returns the first item with the Caption property equal to Value. If the Partial parameter is true, a Caption matches if it starts with the substring Value. If Partial is false, the Caption must match Value exactly. If no item is found, FindCaption returns NULL.


TCustomListView::FindData

TCustomListView	See also

Returns a list view item, if any, associated with the specified data.

TListItem* __fastcall FindData(int StartIndex, void * Value, bool Inclusive, bool Wrap);

Description

Call FindData to locate a list view item with its Data property equal to the Value parameter. If the Inclusive parameter is true, the list item specified by StartIndex is the first item checked. Otherwise, the search starts on the next item. If the Wrap parameter is true, the search continues at the top of the list if a match has not been found before reaching the bottom. FindData returns the first item with a Data property equal to the Value parameter. If no item is found, FindData returns NULL.


TCustomListView::GetDragImages

TCustomListView	See also

Returns a drag cursor if a list item is being dragged.

virtual Controls::TCustomImageList* __fastcall GetDragImages(void);

Description

GetDragImages is called automatically to obtain a list of drag images when the user drags the mouse with the button held down. If the user is dragging a list item, GetDragImages returns the drag image list that is created when the user starts dragging a list item. If the user did not start dragging the mouse over a list item, GetDragImages returns NULL.


TCustomListView::GetItemAt

TCustomListView	See also

Returns the list item at the specified position.

TListItem* __fastcall GetItemAt(int X, int Y);

Description

Call GetItemAt to obtain the TListItem object for the list item found at the position specified by the X and Y parameters. X and Y specify the coordinates of the position, in pixels, relative to the top left corner of the list view. If there is no item at the location, GetItemAt returns NULL.


TCustomListView::GetItemIndex

TCustomListView	See also

Returns the index of the specified item in the Items property array.

int __fastcall GetItemIndex(TListItem* Value);

Description

Call GetItemIndex to determine the position of a list item, where 0 is the index of the first item, 1 is the index of the second item, and so on. If the item specified by the Value property is not in the list view, GetItemIndex returns -1.


TCustomListView::GetNearestItem

TCustomListView	See also

Returns the list item nearest a specified point, in a particular direction.

TListItem* __fastcall GetNearestItem(const tagPOINT &Point, TSearchDirection Direction);

Description

Call GetNearestItem to locate a list item from a position specified in pixel coordinates relative to the top left corner of the list view. GetNearestItem starts looking at the position specified by the Point parameter, and moves in the direction indicated by the Direction parameter until it locates a list item.

The Direction parameter can be one of the following values:

Value	Meaning

sdLeft	GetNearestItem looks to the left of the specified point.

sdRight	GetNearestItem looks to the right of the specified point.

sdAbove	GetNearestItem looks above the specified point.

sdBelow	GetNearestItem looks below the specified point.

sdAll	GetNearestItem returns the closest item in any direction.

If no item is found, GetNearestItem returns NULL.


TCustomListView::GetNextItem

TCustomListView 	See also

Returns the next list item after the StartItem in the specified direction.

TListItem* __fastcall GetNextItem(TListItem* StartItem, TSearchDirection Direction, TItemStates States);

Description

Call GetNextItem to find the next list item after StartItem in the direction given by the Direction parameter. Only items in the state indicated by the States parameter are considered.

The Direction parameter can be one of the following values:

Value	Meaning

sdLeft	GetNextItem looks to the left of the specified item.

sdRight	GetNextItem looks to the right of the specified item.

sdAbove	GetNextItem looks above the specified item.

sdBelow	GetNextItem looks below the specified item.

sdAll	GetNextItem looks in the order that items appear in the Items property.

The States parameter can take the following values:

Value	Meaning

isNone	Only items in the default state are returned

isCut	Only items marked for a cut and paste operation are returned.

isDropHilited	Only items highlighted as a drag-and-drop target are returned

isFocused	The value of the ItemFocused property is returned.

isSelected	Only selected items are returned.


TCustomListView::GetSearchString

TCustomListView	See also

Returns the incremental search string of a list view control.

System::AnsiString __fastcall GetSearchString();

Description

Call GetSearchString to obtain the character sequence typed by the user while the list view has input focus. Each time the user types a character, the list view appends the character to the search string and searches for a matching item. A timeout period of less than a second is associated with each character that the user types. If the timeout period elapses before the user types another character, the incremental search string is reset. If the system finds a match, it selects the item and, if necessary, scrolls it into view.


TCustomListView::InsertItem

TCustomListView	See also

Description

DYNAMIC void __fastcall InsertItem(TListItem* Item);

List view objects call InsertItem internally when new items are added to the Items property list. Override the InsertItem method to cause descendant classes to take specific action in addition to this event when new items are inserted, or to block the OnInsert event from occurring.


TCustomListView::IsEditing

TCustomListView	See also

Indicates whether any item in the list view is being edited.

bool __fastcall IsEditing(void);

Description

Call IsEditing to determine whether the user is editing the caption of any of the items in the list.  IsEditing returns true if the user is editing an item, false otherwise.


TCustomListView::Notification

TCustomListView	See also

Responds to notifications that components are about to be created or destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the parent class's method, Notification checks whether the image list specified by the LargeImages, SmallImages, or StateImages property is about to be destroyed. If so, Notification sets the appropriate property to NULL.


TCustomListView::Scroll

TCustomListView	See also

Scrolls the content of a list view by the indicated amount.

void __fastcall Scroll(int DX, int DY);

Description

Call Scroll to scroll the content of a list view by DX pixels horizontally and DY pixels vertically.


TCustomListView::StringWidth

TCustomListView	See also

Returns the width of a string, using the list view’s current font.

int __fastcall StringWidth(System::AnsiString S);

Description

Call StringWidth to determine the space, in pixels, required to display a string using the list view’s current font.


TCustomListView::UpdateColumn

TCustomListView	See also

Updates the image of the column indicated by Index.

void __fastcall UpdateColumn(int Index);

Description

UpdateColumn is called automatically when the display properties of a column in the list view change. UpdateColumn adjusts the image of the column to match the properties of the TListColumn object indexed by the Index parameter in the Columns property.

UpdateColumn does nothing if ColumnsShowing returns false.


TCustomListView::UpdateColumns

TCustomListView	See also

Causes the list view control to update the image of all columns.

void __fastcall UpdateColumns(void);

Description

UpdateColumns is called automatically when the properties of several columns in the list view change. UpdateColumn adjusts the image of every column to match the properties of the corresponding TListColumn object listed in the Columns property.

UpdateColumns does nothing if ColumnShowing returns false.


TCustomListView::UpdateItems

TCustomListView	See also

Redraws a range of items, starting at FirstIndex and ending at LastIndex.

void __fastcall UpdateItems(int FirstIndex, int LastIndex);

Description

Call UpdateItems after making changes that affect the display image of the list items in the specified range.


TCustomListView::WndProc

TCustomListView	See also

Provides specific message responses for the list view.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc overrides the parent class's method to prevent the list view from redrawing while the items are being updated.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomMaskEdit

Hierarchy	Properties	Methods	See also

TCustomMaskEdit is the abstract base type for edit controls that provide a mask for checking the validity of text typed into the control.

Unit

mask

Description

TCustomMaskEdit introduces new properties and methods to expand the capabilities of TCustomEdit for validity checking using an edit mask. To create an edit control that takes advantage of the masking capabilities of TCustomMaskEdit, use a TMaskEdit object. To create an edit control that does not validate the input, use the TEdit object instead.

Do not create instances of TCustomMaskEdit. Use TCustomMaskEdit as a base class when declaring control objects that implement a masked edit control. Properties and methods of TCustomMaskEdit provide basic behavior that descendant classes inherit as well as behavior that components can override to customize their behavior.


TCustomMaskEdit properties

TCustomMaskEdit	Alphabetically	Legend

In TCustomMaskEdit

EditMask

EditText

IsMasked

MaskState

MaxLength

Text

Derived from TCustomEdit

CanUndo

Modified

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomMaskEdit properties

TCustomMaskEdit	By object	Legend

Align

BoundsRect

Brush

CanUndo

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

EditMask

EditText

Enabled

Handle

Height

HelpContext

Hint

IsMasked

Left

MaskState

MaxLength

Modified

Name

Owner

Parent

ParentWindow

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TCustomMaskEdit::EditMask

TCustomMaskEdit	See also	Example

Specifies the mask that represents what text is valid for the masked edit control.

__property System::AnsiString EditMask = {read=FEditMask, write=SetEditMask};

Description

Use EditMask to restrict the characters a user can enter into the masked edit control to valid characters and formats. If the user attempts to enter an invalid character, the edit control does not accept the character. Validation is performed on a character-by-character basis by the ValidateEdit method.

A mask consists of three fields with semicolons separating the fields. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are saved as part of the data. The third part of the mask is the character used to represent unentered characters in the mask.

These are the special characters used in the first field of the mask:

Character	Meaning in mask

 !	If a ! character appears in the mask, optional characters are represented in the EditText as leading blanks. If a ! character is not present, optional characters are represented in the EditText as trailing blanks.

 >	If a > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a < character is encountered.

 <	If a < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a > character is encountered.

 <>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data.

\	The character that follows a \ character is a literal character. Use this character to use any of the mask special characters as a literal in the data.

 L	The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.

 l	The l character permits only an alphabetic character in this position, but doesn't require it.

A	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.

 a	The a character permits an alphanumeric character in this position, but doesn't require it.

C	The C character requires an arbitrary character in this position.

 c	The c character permits an arbitrary character in this position, but doesn't require it.

 0	The 0 character requires a numeric character only in this position.

 9	The 9 character permits a numeric character in this position, but doesn't require it.

#	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.

:	The : character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.

 /	The / character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.

 ;	The ; character is used to separate the three fields of the mask.

 _	The _ character automatically inserts spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters must be matched exactly in the edit control. They are inserted automatically, and the cursor skips over them during editing. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the text for the edit control. For example, the mask for a telephone number with area code could be the following string:

(000)_000-0000;0;*

The 0 in the second field indicates that the Text property for the edit control would consist of the 10 digits that were entered, rather than the 14 characters that make up the telephone number as it appears in the edit control.

A 0 in the second field indicates that literals should not be included, any other character indicates that they should be included. The character to indicate whether literals should be included can be changed in the EditMask property editor, or programmatically by changing the MaskNoSave typed constant.

The third field of the mask is the character that appears in the edit control for blanks (characters that have not been entered). By default, this is the same as the character that stands for literal spaces. The two characters appear the same in an edit window. However, when a user edits the text in a masked edit control, the cursor selects each blank character in turn, and skips over the space character.

Setting EditMask to an empty string removes the mask.

Note:	When working with multibyte character sets, such as Japanese shift-JIS, each special mask character represents a single byte. To specify double-byte characters using the L, l, A, a, C, or c specifiers, the mask characters must be doubled as well. For example, LL would represent two single-byte alphabetic characters or a one double-byte character. Only single-byte literal characters are supported.


TCustomMaskEdit::EditText

TCustomMaskEdit	See also

Specifies the text that appears in the window of the masked edit control.

__property System::AnsiString EditText = {read=GetEditText, write=SetEditText};

Description

EditText is the value of the text for the edit control after it is formatted using the EditMask. Before the text is fully entered into a masked edit control, the EditText includes a blank character for each unentered character. As characters are entered, the blank characters in the EditText are replaced by the values that the user types.

If literal mask characters are included in the text, and no character is substituted for blanks, the values of EditText and Text are the same.

Note:	EditText only applies at runtime.


TCustomMaskEdit::IsMasked

TCustomMaskEdit	See also 	Example

Indicates whether a mask exists for the edit control.

__property bool IsMasked = {read=GetMasked, nodefault};

Description

Read IsMasked to determine whether the EditMask property has been set. If IsMasked is true, the control has a mask, and input is validated at runtime. If IsMasked is false, the control does not restrict editing at runtime.


TCustomMaskEdit::MaskState

TCustomMaskEdit	See also

Indicates state information about how the mask is being applied.

enum Mask__3 { msMasked, msReEnter, msDBSetText };

typedef Set<Mask__3, msMasked, msDBSetText> TMaskedState;

__property TMaskedState MaskState = {read=FMaskState, write=FMaskState, nodefault};

Description

MaskState is used internally to determine appropriate actions based on how the mask is currently being applied. MaskState is a set drawn from among the following values:

Value	Meaning

msMasked	A mask has been assigned. MaskState includes msMasked when IsMasked is true.

msReEnter	An invalid character has been rejected and the next edit should be a valid replacement character.

msDBSetText	The text comes from a database field and should not be validated.

MaskState is exposed as a protected property so that derived classes can maintain and use this state information in the implementation of properties and methods.


TCustomMaskEdit::MaxLength

TCustomMaskEdit	See also

Specifies the maximum number of characters that can appear in the edit control.

__property int MaxLength = {read=GetMaxLength, write=SetMaxLength, default=0};

Description

MaxLength is the length of the EditText. Set MaxLength to limit the number of characters that can appear in the edit control when there is no EditMask. If there is an EditMask, MaxLength is implied by the mask itself, and cannot be changed. The EditText contains blank characters for each character that has not been entered, padding the end or beginning of every optional section, so it remains constant in length.


TCustomMaskEdit::Text

TCustomMaskEdit	See also

Denotes the underlying text for the masked edit control before the mask has been applied.

__property System::AnsiString Text = {read=GetText, write=SetText};

Description

Use Text to determine the underlying value of the text before it has been formatted by the mask. Text may differ from the EditText visible in the masked edit control if the mask specifies that literal characters should be removed, if the mask includes spaces, or if the mask includes characters that have not yet been filled in by the user. Text will not contain the blank characters, spaces will not be replaced by _, and literal characters in the mask will be removed if the mask indicates they should be.

When setting Text, the value of the text is formatted using the mask, and the resulting EditText is used to update the window.

If there is no mask, Text is the text that appears in the edit control.


TCustomMaskEdit methods

TCustomMaskEdit	Alphabetically	Legend

In TCustomMaskEdit

~TCustomMaskEdit

CheckCursor

Clear

EditCanModify

GetFirstEditChar

GetLastEditChar

GetMaxChars

GetNextEditChar

GetPriorEditChar

GetSel

GetTextLen

KeyDown

KeyPress

KeyUp

ReformatText

Reset

SetCursor

SetSel

TCustomMaskEdit

ValidateEdit

ValidateError

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomMaskEdit methods

TCustomMaskEdit	By object	Legend

~TCustomMaskEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CheckCursor

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EditCanModify

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFirstEditChar

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLastEditChar

GetMaxChars

GetNamePath

GetNextEditChar

GetParentComponent

GetPriorEditChar

GetSel

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

KeyPress

KeyUp

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

ReformatText

Refresh

RemoveComponent

RemoveControl

Repaint

Reset

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetCursor

SetFocus

SetSel

SetSelTextBuf

SetTextBuf

Show

TCustomMaskEdit

Undo

Update

UpdateControlState

ValidateEdit

ValidateError


TCustomMaskEdit::CheckCursor

TCustomMaskEdit	See also

Moves the cursor to the closest editable character and selects it if nothing is currently selected.

void __fastcall CheckCursor(void);

Description

CheckCursor is called whenever the position of the cursor may have changed. It ensures that at least one character is always selected. Because editing a masked edit control consists of replacing the blank characters in the mask, there must always be a selection to replace. The selection corresponds to one or more nonliteral characters in the mask, which are either blank or contain characters for the user to re-enter.


TCustomMaskEdit::Clear

TCustomMaskEdit	See also

Sets the Text property to an empty string.

HIDESBASE void __fastcall Clear(void);

Description

Use Clear to remove all text that was entered into the masked edit control. Clear sets the value of Text to an empty string. It does not clear the EditMask. If the edit control has a mask, EditText will not be empty, but will have all non-literal characters replaced by blanks.


TCustomMaskEdit::TCustomMaskEdit

TCustomMaskEdit	See also

Creates an instance of TCustomMaskEdit.

__fastcall virtual TCustomMaskEdit(Classes::TComponent* AOwner);

__fastcall TCustomMaskEdit(HWND ParentWindow) : Stdctrls::TCustomEdit(ParentWindow) { }

Description

Do not create instances of TCustomMaskEdit. Instead, instantiate one of its descendants such as TMaskEdit. Pass a single Component as a parameter to provide the edit control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the edit control in a non-VCL window. This syntax is used when the edit control is implemented as an ActiveX control that is embedded in a non-VCL window.

TCustomMaskEdit initializes the MaskState and blank substitution character after calling the parent object's constructor.


TCustomMaskEdit::EditCanModify

TCustomMaskEdit	See also

Permits the user to edit the Text.

virtual bool __fastcall EditCanModify(void);

Description

The EditCanModify method defined by TCustomMaskEdit always returns true, allowing the Text to be edited. EditCanModify exists primarily to provide an interface for a method that can conditionally disallow changes to the Text by returning false.


TCustomMaskEdit::GetFirstEditChar

TCustomMaskEdit	See also

Returns the index in the EditMask of the first nonliteral character.

int __fastcall GetFirstEditChar(void);

Description

Use GetFirstEditChar to find the first position of the EditMask where the user can modify the EditText. 0 specifies the first character, 1 the second character, and so on. If there is no mask, GetFirstEditChar returns zero.

Use GetFirstEditChar as a starting point for programmatically processing all the nonliteral characters in the EditText. Use GetNextEditChar to continue to loop through the editable characters in the EditText, and GetLastEditChar to determine when all nonliteral characters have been processed.


TCustomMaskEdit::GetLastEditChar

TCustomMaskEdit	See also

Returns the index in the EditMask of the last nonliteral character.

int __fastcall GetLastEditChar(void);

Description

Use GetLastEditChar to find the last position of the EditMask where the user can modify the EditText. 0 specifies the first character, 1 the second character, and so on. If there is no mask, GetLastEditChar returns the length of the text.


TCustomMaskEdit::GetMaxChars

TCustomMaskEdit	See also

Returns the length of the EditText.

int __fastcall GetMaxChars(void);

Description

If there is a mask, GetMaxChars returns the length of the EditText, including all blanks. This is the same as MaxLength, because editing in a masked edit control consists of replacing nonliteral characters. If there is no mask, GetMaxChars returns the length of the text in the window. In this case, the value returned by GetMaxChars may be less than MaxLength, which is the maximum number of characters that can be entered into the edit control.


TCustomMaskEdit::GetNextEditChar

TCustomMaskEdit	See also

Returns the first index of a nonliteral character equal to or greater than an offset.

int __fastcall GetNextEditChar(int Offset);

Description

Call GetNextEditChar to find the first position of the EditMask at or following Offset where the user can modify the EditText. 0 specifies the first character, 1 the second character, and so on. If there is no nonliteral character at or following Offset, GetNextEditChar returns MaxLength.

Use GetNextEditChar to loop through the editable characters in the EditText, starting with the value returned by GetFirstEditChar and using GetLastEditChar to determine when all nonliteral characters have been processed.


TCustomMaskEdit::GetPriorEditChar

TCustomMaskEdit	See also

Returns the first index of a nonliteral character equal to or less than an offset.

int __fastcall GetPriorEditChar(int Offset);

Description

Call GetPriorEditChar to find the first position of the EditMask at or preceding Offset, where the user can modify the EditText. 0 specifies the first character, 1 the second character, and so on. If there is no nonliteral character at or preceding Offset, GetPriorEditChar returns the index of the first editable character following Offset.


TCustomMaskEdit::GetSel

TCustomMaskEdit	See also

Returns the endpoints of the current selection in the EditText.

void __fastcall GetSel(int &SelStart, int &SelStop);

Description

Use GetSel to obtain the indexes of the first and last selected characters of the EditText, where 0 is the index of the first character. Not all the characters in the selection will necessarily be editable, if the mask contains literal characters. Do not use the resulting indexes on the Text property if there is a mask, because the EditText may contain blanks or nonliteral characters not found in the Text.

To programmatically change the selected text, use GetNextEditChar to cycle through the editable characters of the selection from SelStart to SelStop.


TCustomMaskEdit::GetTextLen

TCustomMaskEdit	See also

Returns the length of the underlying text.

HIDESBASE int __fastcall GetTextLen(void);

Description

Use GetTextLen to determine the length of the underlying text for the masked edit control. The underlying text has not been formatted for display by the mask, and may differ from the EditText that appears in the window of the control.


TCustomMaskEdit::KeyDown

TCustomMaskEdit	See also

Supplements the inherited KeyDown to process navigation keys and the Delete key.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

After calling the inherited KeyDown, KeyDown ensures that moving the cursor within the masked edit control places the cursor on an editable character, and that deleting the current selection replaces nonliteral characters with blanks. Derived objects can override this method to further supplement the processing that takes place when the user presses a key down.


TCustomMaskEdit::KeyPress

TCustomMaskEdit	See also

Supplements the inherited method to process the Esc and Enter keys.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

After calling the inherited method, KeyPress calls the Reset method in response to the Esc key, or calls the ValidateEdit method in response to the Enter key. Derived classes can override this method to further supplement the processing of specific keystrokes.


TCustomMaskEdit::KeyUp

TCustomMaskEdit	See also

Supplements the inherited method to process the Ctrl+Left and Ctrl+Right key combinations.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyUp(Word &Key, Classes::TShiftState Shift);

Description

After calling the inherited method, KeyUp makes sure that selection using the Ctrl+Left and Ctrl+Right key combinations ends with an editable selection in the edit window. Derived classes can override this method to further supplement the processing that takes place when the user releases a key.


TCustomMaskEdit::ReformatText

TCustomMaskEdit	See also

Applies the mask NewMask to the underlying text, and updates the internal representation of the mask.

void __fastcall ReformatText(const System::AnsiString NewMask);

Description

ReformatText does the bulk of the work of setting the EditMask property at runtime. ReformatText should not be used in place of the EditMask property, however, as it does not deal with the MaskState property or the positioning of the cursor.


TCustomMaskEdit::Reset

TCustomMaskEdit	See also

Returns the EditText to its value at the time when the edit control last lost focus.

virtual void __fastcall Reset(void);

Description

Reset cancels the most recent edits to the masked edit control. The EditText returns to the value at the time the control last lost focus, not the time when it first regained focus. Thus, any changes to the EditText that occurred programmatically while the edit control did not have focus will also be discarded.


TCustomMaskEdit::SetCursor

TCustomMaskEdit	See also

Moves the cursor to the first editable character at or before Pos, and selects that character.

HIDESBASE void __fastcall SetCursor(int Pos);

Description

SetCursor handles positioning of the cursor within the EditText so that it is always on an editable character. It also ensures that at least one character is always selected. Because editing a masked edit control consists of replacing the blank characters in the mask, there must always be a selection to replace. The selection corresponds to one or more nonliteral characters in the mask, which are either blank or contain characters for the user to re-enter.


TCustomMaskEdit::SetSel

TCustomMaskEdit	See also

Selects characters in the EditText from SelStart to SelStop.

void __fastcall SetSel(int SelStart, int SelStop);

Description

SetSel selects the indicated range of characters in the EditText, regardless of whether any of them are editable. If SelStart is the same as SelStop, SetSel positions the cursor at the SelStart character. When using SetSel, leave the cursor in an editable position if the intent is to create a selection for the user to replace.

SetSel can be used to select non-editable characters that can then be captured by using the SelText property or by copying to the Clipboard. Once the selection has been captured, return the cursor to an editable position by calling CheckCursor.


TCustomMaskEdit::ValidateEdit

TCustomMaskEdit	See also

Validates the EditText against the current mask.

void __fastcall ValidateEdit(void);

Description

ValidateEdit attempts to validate the EditText after each keystroke, and when the user attempts to leave the masked edit field. If the EditText does not match the specifications of the EditMask, ValidateEdit calls ValidateError to throw an exception, and returns the cursor to the first position where the EditText did not comply with the EditMask.


TCustomMaskEdit::ValidateError

TCustomMaskEdit	See also

Beeps and throws an EDBEditError exception.

void __fastcall ValidateError(void);

Description

ValidateEdit calls ValidateError when the EditText fails to comply with the EditMask.


TCustomMaskEdit::~TCustomMaskEdit

TCustomMaskEdit

Frees the memory associated with the TCustomMaskEdit object.

__fastcall virtual ~TCustomMaskEdit(void) { }

Description

Do not call ~TCustomMaskEdit directly. Instead, use the delete keyword on the object, which causes ~TCustomMaskEdit to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit


TCustomMemo

Hierarchy	Properties	Methods	See also

TCustomMemo is the abstract base type for memo components, which are multiline edit boxes, including TMemo and TDBMemo.

Unit

stdctrls

Description

TCustomMemo introduces new properties and methods to expand the capabilities of TCustomEdit for handling multiline edit boxes.

Do not create instances of TCustomMemo. Use TCustomMemo as a base class when declaring control objects that implement a multiline edit control. Properties and methods of TCustomMemo provide basic behavior that descendant classes inherit as well as behavior that components can override to customize their behavior.


TCustomMemo properties

TCustomMemo	Alphabetically	Legend

In TCustomMemo

Alignment

CaretPos

Lines

ScrollBars

WantReturns

WantTabs

WordWrap

Derived from TCustomEdit

CanUndo

Modified

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomMemo properties

TCustomMemo	By object	Legend

Align

Alignment

BoundsRect

Brush

CanUndo

CaretPos

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Lines

Modified

Name

Owner

Parent

ParentWindow

ScrollBars

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

WantReturns

WantTabs

Width

WindowProc

WordWrap


TCustomMemo::Alignment

TCustomMemo	See also

Determines how the text is aligned within the memo control.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

Use Alignment to change the way the text is formatted by the memo control. Alignment can take one of the following values:

Value	Meaning

taLeftJustify	Align text to the left side of the control

taCenter	Center text horizontally in the control.

taRightJustify	Align text to the right side of the control.


TCustomMemo::CaretPos

TCustomMemo	See also

Indicates the position of the caret in the client area of the memo.

__property tagPOINT CaretPos = {read=GetCaretPos};

Description

Use CaretPos to determine the coordinates of the cursor. CaretPos indicates the X and Y position (in pixels) relative to the client origin of the memo.

To determine the position of the caret in terms of characters of text rather than physical location, use the SelStart property.


TCustomMemo::Lines

TCustomMemo	See also 	Example

Contains the individual lines of text in the memo control.

__property Classes::TStrings* Lines = {read=FLines, write=SetLines};

Description

Use Lines to manipulate text in an memo control on a line-by-line basis. Lines is a TStrings object, so the TStrings methods may be used for Lines to perform manipulations such as counting the lines of text, adding new lines, deleting lines, or replacing lines with new text.

To work with all the text at once, use the Text property. To manipulate individual lines of text, the Lines property works better.


TCustomMemo::ScrollBars

TCustomMemo	See also	Example

Determines whether the memo control has any scroll bars.

enum TScrollStyle { ssNone, ssHorizontal, ssVertical, ssBoth };

__property TScrollStyle ScrollBars = {read=FScrollBars, write=SetScrollBars, default=0};

Description

Use ScrollBars to give a multiline edit control horizontal or vertical scroll bars. ScrollBars can take one of the following values:

Value	Meaning

ssNone	The control has no scroll bars.

ssHorizontal	The control has a single scroll bar on the bottom edge.

ssVertical	The control has a single scroll bar on the right edge.

ssBoth	The control has a scroll bar on both the bottom and right edges.


TCustomMemo::WantReturns

TCustomMemo	See also	Example

Determines whether the user can insert return characters into the text.

__property bool WantReturns = {read=FWantReturns, write=FWantReturns, default=1};

Description

Set WantReturns to true to allow users to enter return characters into the text. Set WantReturns to false to allow the form to handle return characters instead.

For example, in a form with a default button (such as an OK button) and a memo control, if WantReturns is false, pressing Enter chooses the default button. If WantReturns is true, pressing Enter inserts a return character in the text.

Note:	If WantReturns is false, users can still enter return characters into the text by pressing Ctrl+Enter.


TCustomMemo::WantTabs

TCustomMemo	See also	Example

Determines whether the user can insert tab characters into the text.

__property bool WantTabs = {read=FWantTabs, write=FWantTabs, default=0};

Description

Set WantTabs to true to allow users to enter tab characters into the text. Set WantTabs to false if you want the tab character to select the next control on the form instead.

Note:	If WantTabs is true, users can tab into the edit control, but they can’t tab out.


TCustomMemo::WordWrap

TCustomMemo	See also	Example

Determines whether the edit control inserts soft carriage returns so text wraps at the right margin.

__property bool WordWrap = {read=FWordWrap, write=SetWordWrap, default=1};

Description

Set WordWrap to true to make the edit control wrap text at the right margin so it fits in the client area. The wrapping is cosmetic only--the text does not include any return characters that were not explicitly entered. Set WordWrap to false to have the edit control show a separate line only where return characters were explicitly entered into the text.

Note:	There should be no use for a horizontal scroll bar if WordWrap is true.


TCustomMemo methods

TCustomMemo	Alphabetically	Legend

In TCustomMemo

~TCustomMemo

CreateParams

CreateWindowHandle

GetCaretPos

KeyPress

Loaded

SetAlignment

SetLines

SetScrollBars

SetWordWrap

TCustomMemo

Derived from TCustomEdit

Clear

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomMemo methods

TCustomMemo	By object	Legend

~TCustomMemo

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CreateParams

CreateWindowHandle

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetCaretPos

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyPress

Loaded

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetAlignment

SetBounds

SetFocus

SetLines

SetScrollBars

SetSelTextBuf

SetTextBuf

SetWordWrap

Show

TCustomMemo

Undo

Update

UpdateControlState


TCustomMemo::TCustomMemo

TCustomMemo	See also

Creates and initializes an instance of TCustomMemo.

__fastcall virtual TCustomMemo(Classes::TComponent* AOwner);

__fastcall TCustomMemo(HWND ParentWindow) : Stdctrls::TCustomEdit(ParentWindow) { }

Description

Do not create instances of TCustomMemo. TCustomMemo is intended only as a base class for other components. To add a memo component to a form, instantiate a descendant of TCustomMemo such as TMemo, using the new keyword.

Pass a single Component as a parameter to provide the memo with an Owner that is responsible for freeing the memo. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the memo in a non-VCL window. This syntax is used when the memo is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TCustomMemo adjusts some of the properties so that the control starts with the following values:

•	AutoSelect is true.

•	AutoSize is false.

•	BorderStyle is bsSingle.

•	ControlStyle includes csClickEvents, csDoubleClicks, csFixedHeight, and csSetCaption.

•	Height and Width are 89 and 188.

•	HideSelection is true.

•	ParentColor is false.

•	TabStop is true.

•	WantReturns is true.

•	WordWrap is true.

Derived objects that override the TCustomMemo method should call the parent object's constructor before making any additional initializations.


TCustomMemo::TCustomMemo
TCustomMemo::CreateParams

TCustomMemo	See also

Initializes a window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it passes to CreateWindowHandle. TCustomEdit overrides the inherited method to specify a scrollable multiline edit control. The Params parameter is updated to reflect the current values of the Alignment, ScrollBars, and WordWrap properties, in addition to the BorderStyle, HideSelection, PasswordChar, and ReadOnly properties that the inherited method specifies.


TCustomMemo::TCustomMemo
TCustomMemo::CreateWindowHandle

TCustomMemo	See also

Creates a window based on the window-creation parameter record.

virtual void __fastcall CreateWindowHandle(const Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateWindowHandle to create the edit control window once it has been specified in the window-creation parameters. CreateWindowHandle creates the window by calling the CreateWindowEx API function, passing parameters from the record passed in the Params parameter. CreateWindowHandle overrides the inherited method to interpret the Caption in Params as the initial text rather than as the window caption.


TCustomMemo::~TCustomMemo

TCustomMemo	See also

Destroys an instance of TCustomMemo.

__fastcall virtual ~TCustomMemo(void);

Description

Do not call ~TCustomMemo directly in an application. Instead, use the delete keyword, which takes an indirect reference to a memo object.

~TCustomMemo frees the TStrings object that implements the Lines property before calling the parent object's destructor.


TCustomMemo::GetCaretPos

TCustomMemo	See also

Returns the value of the CaretPos property.

virtual tagPOINT __fastcall GetCaretPos(void);

Description

GetCaretPos is the protected implementation of the CaretPos property. Override this method to change the way the caret position is computed.


TCustomMemo::KeyPress

TCustomMemo	See also

Ensures that return characters are not entered into the text when WantReturns is false.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

KeyPress is called automatically when the user presses a key. After calling the inherited KeyPress, which calls the OnKeyPress event handler, KeyPress discards return characters when WantReturns is false.


TCustomMemo::Loaded

TCustomMemo	See also

Initializes the memo control when it is first loaded into memory.

virtual void __fastcall Loaded(void);

Description

Loaded overrides the default so that the Modified property is set to false after loading the control from a stream. Derived classes can override the Loaded method to perform additional initializations after the control is loaded.


TCustomMemo::SetAlignment

TCustomMemo	See also

Sets the Alignment property.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

void __fastcall SetAlignment(Classes::TAlignment Value);

Description

SetAlignment is exposed as a protected method so derived classes can customize their implementation of the Alignment property.


TCustomMemo::SetLines

TCustomMemo	See also

Sets the Lines property.

void __fastcall SetLines(Classes::TStrings* Value);

Description

SetLines is exposed as a protected method so derived classes can customize their implementation of the Lines property.


TCustomMemo::SetScrollBars

TCustomMemo	See also

Sets the ScrollBars property.

enum TScrollStyle { ssNone, ssHorizontal, ssVertical, ssBoth };

void __fastcall SetScrollBars(TScrollStyle Value);

Description

SetScrollBars is exposed as a protected method so derived classes can customize their implementation of the ScrollBars property.


TCustomMemo::SetWordWrap

TCustomMemo	See also

Sets the WordWrap property.

void __fastcall SetWordWrap(bool Value);

Description

SetWordWrap is exposed as a protected method so derived classes can customize their implementation of the WordWrap property.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit


TCustomMemoryStream

Hierarchy	Properties	Methods	See also

TCustomMemoryStream is an abstract base class used as the common ancestor for memory streams.

Unit

classes

Description

Use TCustomMemoryStream as a base class when defining a stream object that can transfer data that is stored in memory. Memory streams are useful for providing file-like access to data that is stored in a less accessible medium. Data can be moved to an internal memory buffer when the memory stream is created. After manipulating the data in a memory stream, the data can be written out to its actual storage medium when the memory stream is destroyed.

Do not instantiate an instance of TCustomMemoryStream. It is an abstract class that implements behavior common to all memory streams. To work with an instance of a memory stream, use one of the descendants of TCustomMemoryStream, such as TMemoryStream or TResourceStream.


TCustomMemoryStream properties

TCustomMemoryStream	Alphabetically	Legend

In TCustomMemoryStream

Memory

Derived from TStream

Position

Size


TCustomMemoryStream properties

TCustomMemoryStream	By object	Legend

Memory

Position

Size


TCustomMemoryStream::Memory

TCustomMemoryStream	See also

Provides direct access to the memory pool allocated for the memory stream.

__property void * Memory = {read=FMemory};

Description

Use Memory to get access to the memory for the stream. The memory for the stream holds the data that is being transferred by means of the memory stream. Size is the number of bytes of Memory that were allocated, and Position is the current position within Memory.

Note:	Memory is a read-only property. Memory can be used to change the contents of the memory, but to set the actual memory the stream works with, descendants of TCustomMemoryStream must assign a pointer to a memory buffer by calling the SetPointer method.


TCustomMemoryStream methods

TCustomMemoryStream	Alphabetically	Legend

In TCustomMemoryStream

~TCustomMemoryStream

Read

SaveToFile

SaveToStream

Seek

SetPointer

TCustomMemoryStream

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCustomMemoryStream methods

TCustomMemoryStream	By object	Legend

~TCustomMemoryStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

SaveToFile

SaveToStream

Seek

SetPointer

TCustomMemoryStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TCustomMemoryStream::Read

TCustomMemoryStream	See also

Reads up to Count bytes from the memory stream into Buffer and advances the current position of the stream by the number of bytes read.

virtual int __fastcall Read(void *Buffer, int Count);

Description

Use Read to read the contents of the memory stream into a buffer, starting at the current position. Read will read up to Count bytes from the current position in Memory. If Count bytes extends beyond the end of the memory buffer, Read will only transfer the data up to the end of the associated memory buffer. Read returns the number of bytes actually transferred to Buffer, and advances the current position accordingly. If the return value is less than Count, it means that reading reached the end of the stream data.

All the other data-reading methods of the memory stream (ReadBuffer, ReadComponent) call Read to do the actual reading.

Note:	Read treats Count as an upper bound. The ReadBuffer method, by contrast, throws an exception if Count bytes cannot be read.


TCustomMemoryStream::SaveToFile

TCustomMemoryStream	See also

Writes the entire contents of the memory stream to the file with a given file name.

void __fastcall SaveToFile(const System::AnsiString FileName);

Description

Use SaveToFile to write the contents of Memory to a file. SaveToFile allows an application to write out the contents of the memory stream without having to explicitly create and free a file stream object. If the named file cannot be created or opened, SaveToFile throws an EFCreateError exception.


TCustomMemoryStream::SaveToStream

TCustomMemoryStream	See also

Writes the entire contents of the memory stream to the stream object specified by Stream.

void __fastcall SaveToStream(TStream* Stream);

Description

Use SaveToStream to copy data that is stored in memory into another storage medium. SaveToStream writes the entire contents of Memory into the indicated stream object, starting at the current position in the stream that was passed as a parameter.

When the Stream parameter is a TFileStream object, SaveToStream does much the same thing as the SaveToFile method. However, SaveToStream writes to the current position in the target stream. Thus, for example, SaveToStream can be used to append the contents of Memory to a file stream, rather than replace the contents of the file the way SaveToFile does.

If the entire contents of the memory stream cannot be written to the target stream, SaveToStream throws an EWriteError exception.


TCustomMemoryStream::Seek

TCustomMemoryStream	See also

Moves the current position of the stream by Offset bytes, relative to the origin specified by Origin.

virtual int __fastcall Seek(int Offset, Word Origin);

Description

Use Seek to move the current position within the memory stream by the indicated offset. Seek allows an application to read from or write to a particular location within the Memory associated with the memory stream.

If Offset is a negative number, the seek is backward from the specified origin. The following table shows the different values of Origin and their meanings for seeking.

Value	Meaning

soFromBeginning	Offset is from the beginning of Memory. Seek moves to the position Offset. Offset must be >= 0.

soFromCurrent	Offset is from the current position. Seek moves to Position + Offset.

soFromEnd	Offset is from the end of Memory. Offset must be <= 0 to indicate a number of bytes before the end of the memory buffer.

Seek returns the new value of the Position property.

Note:	Seek does no error checking on the value provided for Offset. Do not call seek with an offset that would move the current position less than 0 (before the start of Memory) or greater than Size (beyond the end of the memory buffer).


TCustomMemoryStream::SetPointer

TCustomMemoryStream	See also

Replaces the memory buffer associated with the memory stream.

void __fastcall SetPointer(void *Ptr, int Size);

Description

Use SetPointer to set the internal memory buffer, Memory, to be the value passed in by Ptr. Size is the number of bytes Ptr points to.

Descendants of TCustomMemoryStream should use SetPointer to associate the memory stream with the memory buffer that holds the data for the memory stream.

Note:	SetPointer does not free the existing value of Memory, if any, when it replaces the memory buffer. Descendants of TCustomMemoryStream that use SetPointer to replace the stream’s memory pool should free the memory pointed to by the Memory property before calling SetPointer to replace the memory buffer.


Accessibility

Read-only


TCustomMemoryStream::TCustomMemoryStream

TCustomMemoryStream

Creates a new TCustomMemoryStream object.

__fastcall TCustomMemoryStream(void) : Classes::TStream() { }

Description

Do not create instances of TCustomMemoryStream. It is only a base class to memory streams such as TMemoryStream and TResourceStream. To use a memory stream, use the new keyword to instantiate one of these descendant classes.


TCustomMemoryStream::~TCustomMemoryStream

TCustomMemoryStream

Frees the memory associated with the TCustomMemoryStream object.

__fastcall virtual ~TCustomMemoryStream(void) { }

Description

Do not call ~TCustomMemoryStream directly. Instead, use the delete keyword on the object, which causes ~TCustomMemoryStream to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TStream


TCustomPanel

Hierarchy	Properties	Methods	Events	See also

TCustomPanel is the abstract base class for all panel components.

Unit

extctrls

Description

Use TCustomPanel as a base class when defining objects that include other controls as constituent parts. Panel components are controls can contain other controls, grouping them together.

When a panel is aligned with the form using the Align property, it maintains the same relative position to the form even when the form is resized. For example, a panel can be aligned so that it always remains on the top of the form, even when the user changes the shape and size of the form. This makes panels useful for implementing components that act like tool bars or status bars. For example, construct a tool bar or tool palette by adding speed buttons to a panel that execute commands or set modes.


TCustomPanel properties

TCustomPanel	Alphabetically	Legend

In TCustomPanel

Alignment

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

FullRepaint

Locked

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomPanel properties

TCustomPanel	By object	Legend

Align

Alignment

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

FullRepaint

Handle

Height

HelpContext

Hint

Left

Locked

Name

Owner

Parent

ParentColor

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomPanel::Alignment

TCustomPanel	See also

Determines how caption is aligned within the panel.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=2};

Description

Use the Alignment property to specify if the caption of a panel appears on the left, right, or center of the panel. For example, to use a panel as a status bar that displays the TApplication::Hint property as the panel’s Caption property, set Alignment to taLeftJustify to place the hint text on the left side of the panel.

These are the possible values:

Value	Meaning

taLeftJustify	Align text to the left side of the panel

taCenter	Center text horizontally in the panel

taRightJustify	Align text to the right side of the panel


TCustomPanel::BevelInner

TCustomPanel	See also 	Example

Determines the style of the inner bevel of a panel.

enum TPanelBevel { bvNone, bvLowered, bvRaised };

__property TPanelBevel BevelInner = {read=FBevelInner, write=SetBevelInner, default=0};

Description

Use BevelInner to provide the panel with a three-dimensional bevelled look. A panel component has two bevels, an outer bevel drawn next to the border of the control, and an inner bevel drawn inside the outer bevel, separated by the number of pixels specified in the BorderWidth property. The width of the bevels, if they are drawn, is the BevelWidth property.

The BevelInner property determines the style of the inner bevel of a panel component. These are the possible values:

Value	Meaning

bvNone	No inner bevel exists.

bvLowered	The inner bevel is lowered.

bvRaised	The inner bevel is raised.


TCustomPanel::BevelOuter

TCustomPanel	See also 	Example

Determines the style of the outer bevel of a panel.

enum TPanelBevel { bvNone, bvLowered, bvRaised };

__property TPanelBevel BevelOuter = {read=FBevelOuter, write=SetBevelOuter, default=2};

Description

Use BevelOuter to provide the panel with a three-dimensional bevelled look. A panel component has two bevels, an outer bevel drawn next to the border of the control, and an inner bevel drawn inside the outer bevel, separated by the number of pixels specified in the BorderWidth property. The width of the outer bevel is specified in the BevelWidth property in pixels.

These are the possible values:

Value	Meaning

bvNone	No outer bevel exists.

bvLowered	The outer bevel is lowered.

bvRaised	The outer bevel is raised.


TCustomPanel::BevelWidth

TCustomPanel	See also 	Example

Determines the width, in pixels, of both the inner and outer bevels of a panel.

typedef int TBevelWidth;

__property TBevelWidth BevelWidth = {read=FBevelWidth, write=SetBevelWidth, default=1};

Description

Use BevelWidth to specify how wide the inner or outer bevel should be. Don’t confuse BevelWidth, which is the width of the bevels, with BorderWidth, which is the space between the bevels.

If both the BevelInner and BevelOuter properties are bvNone, BevelWidth has no effect. To remove both bevels, set the BevelInner and BevelOuter properties to bvNone, rather than setting the BevelWidth to 0, as this involves less overhead when painting.


TCustomPanel::BorderStyle

TCustomPanel	See also

Determines the style of the line drawn around the perimeter of the panel control.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=0};

Description

Use BorderStyle to specify whether the panel has a single line drawn around it. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border

Don’t confuse the line drawn around the panel with the BorderWidth of the panel. The BorderWidth of the panel is the distance between the outer and inner bevels.


TCustomPanel::BorderWidth

TCustomPanel	See also 	Example

Specifies the distance, in pixels, between the outer and inner bevels.

typedef int TBorderWidth;

__property TBorderWidth BorderWidth = {read=FBorderWidth, write=SetBorderWidth, default=0};

Description

Use BorderWidth to specify how wide the border around the panel should be. A value of 0 means no border should appear.

The border of a panel is the area between the outer and inner bevels. It is visible only if the inner bevel is raised or lowered, but affects the inset of the caption within the panel even if BevelInner is bvNone. If the Alignment property is not taCenter, the Caption will be aligned to the inner edge of the border. This edge is BorderWidth pixels in from the outer bevel if BevelInner is bvNone. It is the inner edge of the inner bevel otherwise.

Don’t confuse the border of the panel with line drawn around the panel itself. The line around the panel is specified by the BorderStyle property.


TCustomPanel::FullRepaint

TCustomPanel	See also

Determines whether the Invalidate method is called when the custom panel receives a WM_SIZE message.

__property bool FullRepaint = {read=FFullRepaint, write=FFullRepaint, default=1};

Description

Set FullRepaint to true to cause the panel and all the controls it contains to be repainted when the panel is resized. If FullRepaint is false, the panel and its controls are not repainted.


TCustomPanel::Locked

TCustomPanel	See also

Determines whether a panel that is being used as a toolbar is replaced by a toolbar supplied by an OLE server.

__property bool Locked = {read=FLocked, write=FLocked, default=0};

Description

Set the Locked property to false when the panel is used as a toolbar by a TOleContainer component. Any panels aligned to a TOleContainer are assumed to be replaceable toolbars unless the Locked property is true. Prevent the panel from being replaced by an OLE server’s toolbar by setting the panel's Locked property to true.

Note:	An OLE application's toolbars must be in panels aligned to a side of the form (that is, their Align properties must be set to alTop, alBottom, alLeft, or alRight).


TCustomPanel events

TCustomPanel	Alphabetically	Legend

In TCustomPanel

OnResize


TCustomPanel events

TCustomPanel	By object	Legend

OnResize


TCustomPanel::OnResize

TCustomPanel	See also

Occurs when the panel is resized while an application is running.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

Write an OnResize event handler to make something happen when the panel is resized. For example, the panel may want to reposition its child controls when it is resized.


TCustomPanel methods

TCustomPanel	Alphabetically	Legend

In TCustomPanel

~TCustomPanel

AlignControls

CreateParams

Paint

Resize

TCustomPanel

Derived from TCustomControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomPanel methods

TCustomPanel	By object	Legend

~TCustomPanel

AlignControls

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CreateParams

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Paint

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

Resize

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomPanel

Update

UpdateControlState


TCustomPanel::AlignControls

TCustomPanel	See also

Aligns any controls contained within the panel.

virtual void __fastcall AlignControls(Controls::TControl* AControl, Windows::TRect &Rect);

Description

Use AlignControls to align all controls within a panel at once. Specify the area in which you want the controls aligned as the value of the Rect parameter.

AlignControls uses the Align property of each child control to determine how to align it. The control passed as the AControl parameter takes precedence in alignment over other, similarly-aligned controls. The AControl parameter can be NULL.


TCustomPanel::TCustomPanel

TCustomPanel	See also

Creates and initializes an instance of TCustomPanel.

__fastcall virtual TCustomPanel(Classes::TComponent* AOwner);

__fastcall TCustomPanel(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Do not create instances of TCustomPanel. Instead, instantiate an appropriate descendant of TCustomPanel, using the new keyword. Panels placed in forms at design time do not need to be explicitly created because they are created automatically.

Pass a single Component as a parameter to provide the panel with an Owner that is responsible for freeing the panel. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the panel in a non-VCL window. This syntax is used when the panel is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TCustomPanel initializes the following properties:

•	Alignment to taCenter.

•	BevelOuter to bvRaised and BevelWidth to 1.

•	BorderStyle to bsNone.

•	Color to BtnFace.

•	ControlStyle to include csAcceptsControls, csCaptureMouse, csClickEvents, csOpaque, csSetCaption, csDoubleClick, and csReplicatable.

•	FullRepaint to true.

•	Height to 41 and Width to 185.


TCustomPanel::TCustomPanel
TCustomPanel::CreateParams

TCustomPanel	See also

Initializes a window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams is called automatically to initialize the window-creation parameters whenever the window for the panel needs to be created. CreateParams overrides the inherited method to implement the BorderStyle property.


TCustomPanel::Paint

TCustomPanel	See also

Renders the image of the panel.

virtual void __fastcall Paint(void);

Description

Override the Paint method to change the way the panel is drawn. The Paint method for custom panels draws the bevels of the panel, sets the brush and font for the panel, and fills in the interior of the panel before calling the Windows API DrawText function to draw the Caption.


TCustomPanel::Resize

TCustomPanel	See also

Generates an OnResize event.

DYNAMIC void __fastcall Resize(void);

Description

Panels call Resize in response to the WM_SIZE message, indicating a change in the size of the panel. Override Resize to provide additional responses in addition to the call to the OnResize event handler.

If the panel’s FullRepaint property is true, Resize invalidates the panel before it calls the OnResize event handler (if it exists).


TCustomPanel::~TCustomPanel

TCustomPanel

Frees the memory associated with the TCustomPanel object.

__fastcall virtual ~TCustomPanel(void) { }

Description

Do not call ~TCustomPanel directly. Instead, use the delete keyword on the object, which causes ~TCustomPanel to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


TCustomProvider

Hierarchy	Properties	Methods	Events	See also

TCustomProvider is the base class for data provision objects in the application server of a multi-tiered database application.

Unit

provider

Description

Use TCustomProvider to derive customized data provider objects for application servers in a multi-tiered database application that bypasses the Borland Database Engine (BDE). TCustomProvider defines the fundamental behaviors required of all provider objects, either through pure virtual method declarations, or through virtual declarations and implementations that are overridden in subsequently derived objects.

In general, a provider derived from TCustomProvider is an intermediate link between a TClientDataSet object on the client, and a dataset object on the application server. It packages data from the server dataset and passes it in one or more transportable blocks to the client dataset.

The client dataset receives the blocked data, and reconstructs it to create a local, in-memory copy of the data for user access. When user access is complete, the client dataset repackages any changed data and sends the updates to the provider on the application server. The provider applies the updates to the remote database server.

TProvider is an example of a BDE-enabled provider derived from TCustomProvider.


TCustomProvider properties

TCustomProvider	Alphabetically	Legend

In TCustomProvider

Constraints

Data

Provider

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomProvider properties

TCustomProvider	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Constraints

Data

DesignInfo

Name

Owner

Provider

Tag

VCLComObject


TCustomProvider::Constraints

TCustomProvider

Controls whether or not database constraints are applied to client requests for data.

__property Word Constraints = {read=FConstraints, write=FConstraints, nodefault};

Description

Set Constraints to specify whether or not constraints defined for the database table or tables underlying a database application server’s dataset components are applied to client requests for data. When Constraints is true (the default), constraints are applied. To disable constraints, set Constraints to false.


TCustomProvider::Data

TCustomProvider	See also

Denotes a data packet created by the provider.

virtual System::OleVariant __fastcall Get_Data();

Description

Data is a read-only property that is used to create a data packet containing all records. As implemented for TCustomProvider, Data calls GetRecords with a parameter of -1.

TCustomProvider::GetRecords returns null. Descendants of TCustomProvider must reimplement the GetRecords method to implement the Data property.


TCustomProvider::Provider

TCustomProvider

Points to the provider interface implemented by the provider component.

__property Stdvcl::_di_IProvider Provider = {read=GetProvider};

Description

Provider is a read-only property that points to the provider interface the provider component uses to communicate with a client dataset.


TCustomProvider events

TCustomProvider	Alphabetically

In TCustomProvider

OnDataRequest


TCustomProvider events

TCustomProvider	By object

OnDataRequest


TCustomProvider::OnDataRequest

TCustomProvider	See also 	Example

Occurs when a provider calls its DataRequest method.

__property TDataRequestEvent OnDataRequest = {read=FOnDataRequest, write=FOnDataRequest};

Declaration

Write an OnDataRequest event handler to do custom processing of data. An application need not use this event handler to work with provider data.

If an application does not provide an OnDataRequest event handler, calls to DataRequest return null.

Note:	To provide the same sort of custom processing on the client side, use an automation method on the remote server.


TCustomProvider methods

TCustomProvider	Alphabetically	Legend

In TCustomProvider

~TCustomProvider

ApplyUpdates

DataRequest

Get_Data

GetMetaData

GetProvider

GetRecords

Reset

SetParams

TCustomProvider

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomProvider methods

TCustomProvider	By object	Legend

~TCustomProvider

ApplyUpdates

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DataRequest

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

Get_Data

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMetaData

GetNamePath

GetParentComponent

GetProvider

GetRecords

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

Reset

SafeCallException

SetParams

TCustomProvider


TCustomProvider::ApplyUpdates

TCustomProvider

Declares an pure virtual method that applies updates received from a client dataset to datasets connected to a remote database server.

virtual System::OleVariant __fastcall ApplyUpdates(const System::OleVariant &Delta, int MaxErrors, int &ErrorCount) = 0;

Description

ApplyUpdates is not implemented for TCustomProvider; it is only declared.

Implement ApplyUpdates in a derived provider component to enable an application server to write a client’s updates to a remote database server. Delta is a variant containing the updated, inserted, and deleted records to write to the database. MaxErrors indicates the maximum number of errors to permit before stopping the update operation; ErrorCount indicates the actual number of errors encountered during the update operation.

ApplyUpdates should return a Variant that is a data packet containing all records that could not be applied to the database.


TCustomProvider::DataRequest

TCustomProvider	See also 	Example

Generates an OnDataRequest event.

virtual System::OleVariant __fastcall DataRequest(const System::OleVariant &Input);

Description

Write an OnDataRequest event handler and call the DataRequest function to invoke the event handler at runtime. This function and the event it invokes enable an application to perform custom processing in response to a request for data.

Note:	Application code must explicitly call DataRequest through the IProvider interface. C++Builder does not call DataRequest.


TCustomProvider::~TCustomProvider

TCustomProvider	See also

Frees an instance of a provider object.

__fastcall virtual ~TCustomProvider(void);

Description

Do not call ~TCustomProvider directly. Instead, use the delete keyword.

 ~TCustomProvider frees all IProvider objects associated with the TCustomProvider object and calls the parent class's destructor.


TCustomProvider.Get_Data

TCustomProvider	See also

Retrieves records from the provider’s dataset source in response to a client request.

virtual System::OleVariant __fastcall Get_Data();

Description

Call Get_Data to retrieve data in response to a client request. Get_Data retrieves all records at once from the provider’s dataset. The provider retrieves data from a dataset source, assembles it into a data packet, and passed the packet to the client as a variant.

Get_Data calls GetRecords with a parameter of -1.


TCustomProvider::GetMetaData

TCustomProvider	See also

Retrieves a data packet containing a dataset’s metadata.

virtual System::OleVariant __fastcall GetMetaData();

Description

Call GetMetaData to retrieve a metadata description of the records in the dataset. GetMetaData calls GetRecords with a parameter of 0.


TCustomProvider::GetProvider

TCustomProvider 	See also

Creates a new provider interface object for the provider.

virtual Stdvcl::_di_IProvider __fastcall GetProvider();

Description

Call GetProvider to establish a new provider interface (IProvider) for a provider component. Each call to GetProvider creates a new provider interface and adds that interface to an internal list of IProvider interfaces maintained by the provider component.


TCustomProvider::GetRecords

TCustomProvider	See also

Retrieves data from a provider’s dataset.

virtual System::OleVariant __fastcall GetRecords(int Count, int &RecsOut);

Description

Override GetRecords in derived provider components to enable an application to retrieve a specified number of records from the provider’s dataset. Count indicates the number or type of records to retrieve. If Count is -1, all records should be retrieved. If Count is 0, only metadata should be retrieved. If Count is greater than 0, only the specified number of records should be retrieved. RecsOut indicate the actual number of records retrieved. Records are returned as a data packet in a Variant .

A client application calls a provider’s GetRecords method to retrieve a partial set of all available records from a dataset. GetRecords is especially useful when dealing with very large datasets, or when working with datasets that have blob fields.

As implemented for TCustomProvider, GetRecords always returns NULL.


TCustomProvider::Reset

TCustomProvider	See also

Implements a virtual method for restarting record fetching at the start of a dataset.

virtual void __fastcall Reset(Word MetaData);

Description

Override Reset in derived provider components to enable an application to start fetching records from the beginning of a dataset after having fetched sequential blocks of records with repeated calls to GetRecords. Otherwise each fetch operation starts at the record following the last record fetched in the previous call to GetRecords.

MetaData should indicate whether or not the next call to fetch records should include metadata. If MetaData is true, the next fetch should return metadata. If false, only data should be returned.

As implemented for TCustomProvider, Reset does nothing.


TCustomProvider::SetParams

TCustomProvider

Implements a virtual method for passing parameters to the dataset.

virtual void __fastcall SetParams(const System::OleVariant &Values);

Description

Override SetParams in derived provider components to enable an application to pass parameters using the provider component. Values is a variant containing the parameters to pass. If the dataset to which parameters are sent represents a query or stored procedure, parameters should be assigned to the parameters of the query or stored procedure. If the dataset to which parameters are sent represents a database table, parameters should be used to set a range for the table.

Values can be in one of three forms:

•	To pass a single parameter, Values is a singe value.

•	To pass multiple parameters without parameter names, Values is a variant array containing the values to use.

•	To pass one or more named parameters, Values is a variant array where each element of the array contains a parameter name and a parameter value.  This option allows clients to make changes to a selection of parameters out of a larger possible number of parameters.

As implemented in TCustomProvider, SetParams does nothing.


TCustomProvider::TCustomProvider

TCustomProvider

Creates a new TCustomProvider object.

__fastcall virtual ~TCustomProvider(void);

Description

Do not create instances of TCustomProvider. This class contains many pure virtual methods and is intended only as a base class.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TCustomRadioGroup

Hierarchy	Properties	Methods	See also

TCustomRadioGroup is the base class for radio-group components.

Unit

extctrls

Description

Radio groups are collections of radio buttons in a single group box. TCustomRadioGroup is the class from which radio-group components—including TRadioGroup and TDBRadioGroup—descend.

Radio buttons that are contained directly in the same control component are said to be “grouped.” When the user checks a radio button, all other radio buttons in its group become unchecked. Hence, two radio buttons on a form can be checked at the same time only if they are placed in separate containers, such as group boxes.


TCustomRadioGroup properties

TCustomRadioGroup	Alphabetically	Legend

In TCustomRadioGroup

Columns

ItemIndex

Items

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomRadioGroup properties

TCustomRadioGroup	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

ItemIndex

Items

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomRadioGroup::Columns

TCustomRadioGroup

Specifies number of columns in the radio group.

__property int Columns = {read=FColumns, write=SetColumns, default=1};

Description

The Columns property determines the number of columns in the radio group. Its value can range from 1 to 16. The default value is 1, which means that the radio buttons are arranged in a single vertical line.


TCustomRadioGroup::ItemIndex

TCustomRadioGroup 	Example

Indicates which radio button in the group is currently selected.

__property int ItemIndex = {read=FItemIndex, write=SetItemIndex, default=-1};

Description

ItemIndex holds the ordinal number of the selected radio button in the Items list. (The first button is 0.) The value of ItemIndex changes at runtime as the user selects radio buttons. If you want one of the buttons to appear selected when the application starts, assign that button to ItemIndex at design time; otherwise, leave ItemIndex set to the default value of -1, which means that no button is selected.


TCustomRadioGroup::Items

TCustomRadioGroup	See also 	Example

Lists the radio buttons in the radio group.

__property Classes::TStrings* Items = {read=FItems, write=SetItems};

Description

Items holds a TStrings object that lists the captions of the radio buttons in the group. In TCustomRadioGroup descendants TRadioGroup and TDBRadioGroup, where this property is published, radio buttons can be added or removed by editing the Items list from the Object Inspector.

Note:	The items in a radio-group object are special instances of TRadioButton generated by TCustomRadioGroup. Independently created TRadioButton instances cannot be included in a radio group.


TCustomRadioGroup methods

TCustomRadioGroup	Alphabetically	Legend

In TCustomRadioGroup

~TCustomRadioGroup

CanModify

GetChildren

ReadState

TCustomRadioGroup

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomRadioGroup methods

TCustomRadioGroup	By object	Legend

~TCustomRadioGroup

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CanModify

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetChildren

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

ReadState

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomRadioGroup

Update

UpdateControlState


TCustomRadioGroup::CanModify

TCustomRadioGroup	See also

Determines whether the user can select a different radio button in the group.

virtual bool __fastcall CanModify(void);

Description

Event handlers call CanModify to verify that the user is allowed to select a different radio button in the group. As defined in TCustomRadioGroup, this method always returns true; override it to return false in situations where the user should not be able to make changes.


TCustomRadioGroup::TCustomRadioGroup

TCustomRadioGroup	See also

Creates and initializes a TCustomRadioGroup instance.

__fastcall virtual TCustomRadioGroup(Classes::TComponent* AOwner);

TCustomRadioGroup(HWND ParentWindow) : Stdctrls::TCustomGroupBox(ParentWindow) { }

Description

Do not instantiate a TCustomRadioGroup object. To add a radio group to a form, create an instance of a TCustomRadioGroup descendant using the new keyword.

Pass a single component as a parameter to provide the radio group with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the radio group in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the radio group is implemented as an ActiveX control.

TCustomRadioGroup calls the parent object's constructor method and initializes TCustomRadioGroup’s properties. It sets the ControlStyle property’s csSetCaption and csDoubleClicks flags.


TCustomRadioGroup::~TCustomRadioGroup

TCustomRadioGroup 	See also

Destroys the TCustomRadioGroup instance and the radio buttons it contains.

__fastcall virtual ~TCustomRadioGroup(void);

Description

Do not call ~TCustomRadioGroup directly. Instead, use the delete keyword on the object, which causes ~TCustomRadioGroup to be invoked automatically.

~TCustomRadioGroup frees the memory for each item in the group, then calls the parent object's destructor method.


TCustomRadioGroup::GetChildren

TCustomRadioGroup	See also

Prevents the streaming system from loading and saving child controls in the usual fashion.

DYNAMIC void __fastcall GetChildren(Classes::TGetChildProc &Proc, Classes::TComponent* Root);

Description

GetChildren is called in the streaming sequence that loads and saves VCL components. Because radio groups load and save their buttons using the ReadState and WriteState methods, TCustomRadioGroup overrides TWinControl to disable the GetChildren method.


TCustomRadioGroup::ReadState

TCustomRadioGroup	See also

Reads the radio group’s data from a stream.

virtual void __fastcall ReadState(Classes::TReader* Reader);

Description

ReadState is part of a sequence of calls used by the streaming system that loads and saves VCL components.  It reads the values of all the radio groups published properties, stored data, and owned components from the reader object passed in Reader. Do not call ReadState directly.

ReadState calls the inherited ReadState method to read the radio group’s published properties and other stored data to a reader object. It then initializes and redraws the buttons in the group.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGroupBox


TCustomRemoteServer

Hierarchy	Properties	Methods	Events	See also

TCustomRemoteServer is the base class for a remote server connection in a client application that is part of a multi-tiered application.

Unit

dbclient

Description

TCustomRemoteServer is the base class object from which a developer can derive a remote server connection object for a client application that is part of a multi-tiered database application. Remote server objects derived from TCustomRemoteServer establish a connection between a client application and an application server.

Developers should not instantiate TCustomRemoteServer objects in their applications. Instead they should either use the TMIDASConnection or TRemoteServer object to establish connections, or they should derive their own custom connection object from TCustomRemoteServer.


TCustomRemoteServer properties

TCustomRemoteServer	Alphabetically	Legend

In TCustomRemoteServer

ClientDataSets

Connected

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomRemoteServer properties

TCustomRemoteServer	By object	Legend

ClientDataSets

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Connected

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomRemoteServer::ClientDataSets

TCustomRemoteServer	See also

Lists client datasets associated with the remote server.

__property Classes::TList* ClientDataSets = {read=FDataSets};

Description

Use ClientDataSets to examine the list of TClientDataSet components that use this remote server component’s connection to establish links to provider objects.


TCustomRemoteServer::Connected

TCustomRemoteServer	See also

Indicates whether or not the remote server object is connected to a remote application server.

__property bool Connected = {read=GetConnected, write=SetConnected, default=0};

Description

Use Connected to read or set the current connection status for a remote server object. By default, Connected is false because the GetConnected method that reads the current value of Connected always returns false.

Developers who derive their own remote server objects from TCustomRemoteServer should override GetConnected to return true when a connection is established, and should override DoConnect and DoDisconnect.


TCustomRemoteServer events

TCustomRemoteServer	Alphabetically	Legend

In TCustomRemoteServer

AfterConnect

AfterDisconnect

BeforeConnect

BeforeDisconnect


TCustomRemoteServer events

TCustomRemoteServer	By object	Legend

AfterConnect

AfterDisconnect

BeforeConnect

BeforeDisconnect


TCustomRemoteServer::AfterConnect

TCustomRemoteServer	See also

Occurs after a remote server establishes a connection with an application server.

__property Classes::TNotifyEvent AfterConnect = {read=FAfterConnect, write=FAfterConnect};

Description

Write an AfterConnect event handler to take application-specific actions after a remote server establishes a connection to an application server.


TCustomRemoteServer::AfterDisconnect

TCustomRemoteServer	See also

Occurs after a remote server drops a connection to an application server.

__property Classes::TNotifyEvent AfterDisconnect = {read=FAfterDisconnect, write=FAfterDisconnect};

Description

Write an AfterDisconnect event handler to take application-specific actions after a remote server drops a connection to an application server.


TCustomRemoteServer::BeforeConnect

TCustomRemoteServer	See also

Occurs before a remote server establishes a connection with an application server.

__property Classes::TNotifyEvent BeforeConnect = {read=FBeforeConnect, write=FBeforeConnect};

Description

Write an BeforeConnect event handler to take application-specific actions before a remote server establishes a connection to an application server.


TCustomRemoteServer::BeforeDisconnect

TCustomRemoteServer	See also

Occurs before a remote server drops a connection to an application server.

__property Classes::TNotifyEvent BeforeDisconnect = {read=FBeforeDisconnect, write=FBeforeDisconnect};

Description

Write an BeforeDisconnect event handler to take application-specific actions before a remote server drops a connection to an application server.


TCustomRemoteServer methods

TCustomRemoteServer	Alphabetically	Legend

In TCustomRemoteServer

~TCustomRemoteServer

AddDataSet

DoConnect

DoDisconnect

GetConnected

GetProvider

GetProviderNames

Loaded

RemoveDataSet

SetConnected

TCustomRemoteServer

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomRemoteServer methods

TCustomRemoteServer	By object	Legend

~TCustomRemoteServer

AddDataSet

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

DoConnect

DoDisconnect

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetConnected

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetProvider

GetProviderNames

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Loaded

MethodAddress

MethodName

NewInstance

RemoveComponent

RemoveDataSet

SafeCallException

SetConnected

TCustomRemoteServer


TCustomRemoteServer::AddDataSet

TCustomRemoteServer	See also

Adds a client dataset to those known by the server connection.

virtual void __fastcall AddDataSet(TClientDataSet* DataSet);

Description

AddDataSet adds a specified client dataset to those that can use this remote server’s connection to an application server. This procedure is called automatically by client dataset objects.


TCustomRemoteServer::TCustomRemoteServer

TCustomRemoteServer	See also

Instantiates an instance of a remote server component.

__fastcall virtual TCustomRemoteServer(Classes::TComponent* AOwner);

Description

Do not create instances of TCustomRemoteServer. TCustomRemoteServer is intended only as a base class for components that connect to remote servers.

TCustomRemoteServer instantiates an instance of a remote server component. It calls its parent object’s constructor and creates an empty list for storing the names of client datasets that use this instance of the remote server.


TCustomRemoteServer::~TCustomRemoteServer

TCustomRemoteServer	See also

Frees this instance of the remote server component.

__fastcall virtual ~TCustomRemoteServer(void);

Description

Do not call ~TCustomRemoteServer directly. Instead, use the delete keyword. ~TCustomRemoteServer drops the connection to an application server, frees the component’s list of client datasets, and calls its parent class’s destructor.


TCustomRemoteServer::DoConnect

TCustomRemoteServer	See also

Provides the interface for a method that forms a connection to an application server.

virtual void __fastcall DoConnect(void);

Description

Descendant classes override the DoConnect method to establish a connection from the remote server component to an application server that brokers data through provider interfaces. As implemented for TCustomRemoteServer, DoConnect is an empty procedure.

For an example of a DoConnect implementation using ActiveX, and a dual interface, see the source code for TRemoteServer.


TCustomRemoteServer::DoDisconnect

TCustomRemoteServer	See also

Provides the interface for a method that drops the connection to an application server.

virtual void __fastcall DoDisconnect(void);

Description

Descendant classes override the DoDisconnect method to drop a connection between the remote server component and an application server that brokers data through provider interfaces. As implemented for TCustomRemoteServer, DoDisconnect is an empty procedure.


TCustomRemoteServer::GetConnected

TCustomRemoteServer	See also

Provides the interface for a method that implements the Connected property.

virtual bool __fastcall GetConnected(void);

Description

Descendant classes override this function to read the current value of the Connected property. As defined for TCustomRemoteServer, GetConnected always returns false.


TCustomRemoteServer::GetProvider

TCustomRemoteServer	See also

Provides the interface for a method that returns a pointer to the IProvider interface established by the provider object on the application server.

virtual Stdvcl::_di_IProvider __fastcall GetProvider(const System::AnsiString ProviderName);

Description

Descendant classes override this function to return the IProvider interface established by the application server when a client application connects to the server. The interface is used by client datasets to request data from the server and send updates to the server to be applied to a remote database server.


TCustomRemoteServer::GetProviderNames

TCustomRemoteServer	See also

Provides the interface for a method that retrieves a list of all available provider objects from an application server into a list created and maintained by the remote server.

typedef void __fastcall (__closure *TGetStrProc)(const System::AnsiString S);

virtual void __fastcall GetProviderNames(Classes::TGetStrProc &Proc);

Description

Descendant classes override this procedure to return a list of all available IProvider interfaces established by the application server when this client application connects to the server. Interfaces can then be made available to client datasets that use this remote server.

As implemented for TCustomRemoteServer, GetProviderNames is an empty procedure.


TCustomRemoteServer::Loaded

TCustomRemoteServer	See also

Prepares a remote server component for connecting to an application server during form loading.

virtual void __fastcall Loaded(void);

Description

Applications should have no need to call Loaded. This procedure is called automatically when the remote server is loaded into memory. Loaded prepares a remote server component for connecting to an application server.


TCustomRemoteServer::RemoveDataSet

TCustomRemoteServer	See also

Removes a client dataset from those known by the server connection.

virtual void __fastcall RemoveDataSet(TClientDataSet* DataSet);

Description

RemoveDataSet removes a specified client dataset from its list of those that can use this remote server’s connection to an application server. This procedure is called automatically by client dataset objects.


TCustomRemoteServer::SetConnected

TCustomRemoteServer	See also

Establishes or drops a connection between a client application and a remote application server.

virtual void __fastcall SetConnected(bool Value);

Description

Call SetConnected to establish or drop a connection from the remote server to an application server. If Value is true, SetConnected calls the BeforeConnect event handler, establishes a connection, and calls the AfterConnect event handler. If Value is false, SetConnected calls the BeforeDisconnect event handler, drops the connection, and calls the AfterDisconnect event handler.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TCustomRichEdit

Hierarchy	Properties	Methods	Events	See also

TCustomRichEdit is the abstract base type for rich edit controls such as TRichEdit.

Unit

comctrls

Description

TCustomRichEdit introduces new properties and methods to expand the capabilities of TCustomMemo for rich text.

Do not create instances of TCustomRichEdit. Use TCustomRichEdit as a base class when declaring control objects that implement rich text capabilities in an edit control. Properties and methods of TCustomRichEdit provide basic behavior that descendant classes inherit as well as behavior that components can override to customize their behavior.


TCustomRichEdit properties

TCustomRichEdit	Alphabetically	Legend

In TCustomRichEdit

DefAttributes

DefaultConverter

HideScrollBars

HideSelection

Lines

PageRect

Paragraph

PlainText

SelAttributes

SelLength

SelStart

SelText

Derived from TCustomMemo

CaretPos

Derived from TCustomEdit

CanUndo

Modified

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomRichEdit properties

TCustomRichEdit	By object	Legend

Align

BoundsRect

Brush

CanUndo

CaretPos

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DefAttributes

DefaultConverter

DesignInfo

Enabled

Handle

Height

HelpContext

HideScrollBars

HideSelection

Hint

Left

Lines

Modified

Name

Owner

PageRect

Paragraph

Parent

ParentWindow

PlainText

SelAttributes

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TCustomRichEdit::DefAttributes

TCustomRichEdit	See also	Example

Describes the rich text characteristics of the default font for the rich edit control

__property TTextAttributes* DefAttributes = {read=FDefAttributes, write=SetDefAttributes};

Description

Use DefAttributes to discover or set the default font characteristics that the rich edit control uses for newly inserted text. These are the characteristics of the text before any special attributes have been applied. Once any special attributes are applied to a portion of text, no text from that point on is considered to have the default attributes, even if the attributes match the DefAttributes.

For example, if a rich edit control has had no attributes applied, the entire text has the default attributes. Selecting a portion of text in the middle and applying a specific attribute (such as a font change) results in three sections: a first section with the default attributes, a middle section with the applied attribute, and a final section with a non-default set of attributes that match the default attributes. Changing the DefAttributes property affects only the first section.

When inserting new text, the font characteristics of the new text will match the font characteristics at the cursor position, or, if the typing replaces a selection, the font characteristics of the selected text. New text will only have the default attributes when typed into the section of text that has the default attributes.

Note:	DefAttributes is available only at runtime.


TCustomRichEdit::DefaultConverter

TCustomRichEdit	See also

Specifies the class of the TConversion object that is used to convert between native file format and the internal format of a rich text control when working with files that do not have a registered extension.

__property System::TMetaClass* DefaultConverter = {read=FDefaultConverter, write=FDefaultConverter}

Description

Use DefaultConverter to specify the type of conversion to use when streaming text to or from files that do not have a registered extension. If DefaultConverter is not set, TCustomRichEdit uses TConversion, which performs no actual conversion. TCustomRichEdit encodes text attributes in rich-text format (RTF). Thus, unrecognized file extensions lead to no conversion, which works for files that contain plain text or any subset of RTF format.

To support streaming to or from files that encode rich text characteristics in some other format, register a conversion format with the file extension used by those files. Use DefaultConverter only to change the conversion that is used for unrecognized file extensions.

Note:	Use the Lines property to stream the text to or from a file.


TCustomRichEdit::HideScrollBars

TCustomRichEdit	See also	Example

Determines whether the scroll bars disappear when not needed.

__property bool HideScrollBars = {read=FHideScrollBars, write=SetHideScrollBars, default=1};

Description

Use HideScrollBars to determine whether the scroll bars disappear from the edit control when the text appears completely within the edit window. Set HideScrollBars to false to prevent the scroll bars from flashing on and off when the contents of the rich edit control change.

HideScrollBars does nothing when the ScrollBars property is set to ssNone (The default for TRichEdit).


TCustomRichEdit::HideSelection

TCustomRichEdit	See also	Example

Determines whether the visual indication of the selected text remains when focus shifts to another control.

__property bool HideSelection = {read=FHideSelection, write=SetHideSelection, default=1};

Description

Set HideSelection to false when it is important to provide visual feedback of the selected portion of the text even when the edit control does not have focus. Set HideSelection to true to make the visual indication of selection appear only when the edit control has focus. HideSelection does not affect the actual value of the selection, only the visual indication. Always setting HideSelection to false can make forms containing many edit controls look busy.


TCustomRichEdit::Lines

TCustomRichEdit	See also	Example

Contains the individual lines of text in the rich text edit control.

__property Classes::TStrings* Lines = {read=FRichEditStrings, write=SetRichEditStrings};

Description

Use Lines to manipulate the text in the rich text edit control on a line by line basis. Lines is a TStrings object, so TStrings methods may be used for Lines to perform manipulations such as counting the lines of text, adding lines, deleting lines, or replacing the text in lines.

To work with the text as one chunk, use the Text property. To manipulate individual lines of text, the Lines property works better.


TCustomRichEdit::PageRect

TCustomRichEdit	See also

Specifies the dimensions, in twips, of the logical page size used when printing the contents of a rich text edit control.

__property Windows::TRect PageRect = {read=FPageRect, write=FPageRect};

Description

Use PageRect to specify the logical page size used when formatting the contents of the rich edit control for printing. Specify the dimensions in twips (1/20 of a point).


TCustomRichEdit::Paragraph

TCustomRichEdit	See also	Example

Specifies the formatting information for the current paragraphs.

__property TParaAttributes* Paragraph = {read=FParagraph};

Description

Read Paragraph to get the TParaAttributes object used by the rich edit control to specify paragraph formatting information. Use the TParaAttributes object to read or write the paragraph formatting information for the current paragraphs. Paragraph formatting information includes alignment, indentation, numbering, and tabs.

Paragraph is a read-only property, because a TCustomRichEdit object has only one TParaAttributes object, which cannot be changed. The attributes of the current paragraphs, however, can be changed, by setting the properties of the TParaAttributes object. These can be set one by one, or all can be set to the value of an existing TParaAttributes object by using Paragraph->Assign.

The current paragraphs are the paragraphs that contain the selected text. If no text is selected, the current paragraph is the one containing the cursor.

Note:	Paragraph is available only at runtime.


TCustomRichEdit::PlainText

TCustomRichEdit	See also	Example

Controls whether the rich edit control treats the text as plain text or rich text when streaming to or from a file.

__property bool PlainText = {read=GetPlainText, write=SetPlainText, default=0};

Description

To write the rich text in the control to a plain text file, set PlainText to true before streaming the text to a file. To ignore the rich text information encoded in a file, set PlainText to true before streaming the text to the control. To stream in the rich text attributes encoded in a file, or save the encoding of the rich text attributes to a file, set PlainText to false.

If the rich text attributes of a file are encoded in some format other than rich text format (RTF), it is necessary to use a converter on the text, even when PlainText is true.

Note:	Rich edit controls do not directly support streaming. Use the Lines property to stream to or from a file.


TCustomRichEdit::SelAttributes

TCustomRichEdit	See also	Example

Describes the rich text characteristics of the selected text in the rich edit control.

__property TTextAttributes* SelAttributes = {read=FSelAttributes, write=SetSelAttributes};

Description

Use SelAttributes to discover or set the font characteristics of the currently selected text. SelAttributes is a TTextAttributes object, which specifies characteristics such as font face, color, size, style, and pitch. To change a single attribute of the currently selected text, read SelAttributes, and set one of its properties. To change all of the attributes of the currently selected text, set SelAttributes to a TTextAttributes object that represents the desired configuration of attributes. If no text is selected, SelAttributes represents the attributes of the cursor position.

When inserting new text, the font characteristics of the new text will match SelAttributes.

Note:	SelAttributes is available only at runtime.


TCustomRichEdit::SelLength

TCustomRichEdit	See also	Example

Specifies the number of characters that are selected.

__property int SelLength = {read=GetSelLength, write=SetSelLength, nodefault};

Description

Read SelLength to determine the length, in characters, of the selected text. Set SelLength to change the selection to consist of the first SelLength characters starting at SelStart.

Note:	Setting SelLength to a value greater than the number of characters from SelStart to the end of the text results in the selection of all characters from SelStart to the end of the text. Reading SelLength immediately after setting it to a value greater than the number of available characters returns the number of characters actually selected, not the value that was just set.


TCustomRichEdit::SelStart

TCustomRichEdit	See also	Example

Specifies the position of the first selected character in the text.

__property int SelStart = {read=GetSelStart, write=SetSelStart, nodefault};

Description

Read SelStart to determine the position of the first selected character, where 0 indicates the first character. If there is no selected text, SelStart indicates the position of the cursor. Set SelStart to remove the current selection and position the cursor just before the indicated character.

To select a particular range of the text, first set SelStart to position the cursor, and then set SelLength to extend the selection.


TCustomRichEdit::SelText

TCustomRichEdit	See also

Denotes the selected portion of the edit control’s text.

__property System::AnsiString SelText = {read=GetSelText, write=SetSelText};

Description

Read SelText to determine the value of the selected text. Set SelText to replace the selected text with a new string. If there is no selection, but the edit control has focus, set SelText to insert a new string into the text at the cursor.


TCustomRichEdit events

TCustomRichEdit	Alphabetically	Legend

In TCustomRichEdit

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange


TCustomRichEdit events

TCustomRichEdit	By object	Legend

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange


TCustomRichEdit::OnProtectChange

TCustomRichEdit	See also

Occurs when a user attempts to modify text that is marked as protected.

typedef void __fastcall (__closure *TRichEditProtectChange)(System::TObject* Sender, int StartPos, int EndPos, bool &AllowChange);

__property TRichEditProtectChange OnProtectChange = {read=FOnProtectChange, write=FOnProtectChange};

Description

Write an OnProtectChange event handler to allow modification of text with the protected attribute. The StartPos and EndPos parameters indicate the beginning and end of the range of text that would be affected by the modification, where 0 is the first character in the text. To allow modification of protected text, set AllowChange to true.

To set or unset the protected attribute for a section of text, select the text and use the Protected property of the rich edit control’s SelAttributes property. To cause text to have the protected attribute by default, use the Protected property of the rich edit object’s DefAttributes property.


TCustomRichEdit::OnResizeRequest

TCustomRichEdit	See also 	Example

Occurs when the text has grown either smaller or larger than the control's window size.

typedef void __fastcall (__closure *TRichEditResizeEvent)(System::TObject* Sender, const Windows::TRect &Rect);

__property TRichEditResizeEvent OnResizeRequest = {read=FOnResizeRequest, write=FOnResizeRequest};

Description

Write an OnResizeRequest event handler to respond to notifications that the edit control is trying to resize due to changes in the text. The Rect parameter gives the desired bounding rectangle that will display all the text, in screen coordinates.


TCustomRichEdit::OnSaveClipboard

TCustomRichEdit	See also

Occurs when the window of the edit control is about to be destroyed and the edit control has delayed rendering of text copied to the clipboard.

typedef void __fastcall (__closure *TRichEditSaveClipboard)(System::TObject* Sender, int NumObjects, int NumChars, bool &SaveClipboard);

__property TRichEditSaveClipboard OnSaveClipboard = {read=FOnSaveClipboard, write=FOnSaveClipboard}

Description

Write an OnSaveClipboard event handler to respond to notifications that the window of the edit control is about to be destroyed and the Clipboard needs information from the edit control. The parameter NumObjects is the number of objects on the Clipboard, and NumChars is the number of characters on the Clipboard. To clear all information about the edit control from the Clipboard, set SaveClipboard to false.


TCustomRichEdit::OnSelectionChange

TCustomRichEdit	See also	Example

Occurs when the current selection changes.

__property Classes::TNotifyEvent OnSelectionChange = {read=FOnSelChange, write=FOnSelChange};

Description

Write an OnSelectionChange event handler to respond to changes in the selected text. Changes in selection can occur when the user changes the selection using the mouse or keyboard, or when the selection is changed through the SelText property. Portions of the selection can be changed through the Lines property.


TCustomRichEdit methods

TCustomRichEdit	Alphabetically	Legend

In TCustomRichEdit

~TCustomRichEdit

Clear

CreateParams

CreateWnd

DestroyWnd

DoSetMaxLength

FindText

GetSelLength

GetSelStart

GetSelText

GetSelTextBuf

Print

RegisterConversionFormat

RequestSize

SelectionChange

SetSelLength

SetSelStart

TCustomRichEdit

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomRichEdit methods

TCustomRichEdit	By object	Legend

~TCustomRichEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CreateParams

CreateWnd

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DestroyWnd

DisableAlign

Dispatch

DoSetMaxLength

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

FindText

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelLength

GetSelStart

GetSelText

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Print

Realign

Refresh

RegisterConversionFormat

RemoveComponent

RemoveControl

Repaint

RequestSize

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SelectionChange

SendToBack

SetBounds

SetFocus

SetSelLength

SetSelStart

SetSelTextBuf

SetTextBuf

Show

TCustomRichEdit

Undo

Update

UpdateControlState


TCustomRichEdit::Clear

TCustomRichEdit	See also

Deletes all text from the rich edit control.

virtual void __fastcall Clear(void);

Description

Use Clear to replace the Text property with an empty string. Clear removes all text, not just the selected text. To remove just the selected text, use ClearSelection.


TCustomRichEdit::TCustomRichEdit

TCustomRichEdit	See also

Creates an instance of TCustomRichEdit.

__fastcall virtual TCustomRichEdit(Classes::TComponent* AOwner);

__fastcall TCustomRichEdit(HWND ParentWindow) : Stdctrls::TCustomMemo(ParentWindow) { }

Description

Do not create instances of TCustomRichEdit. Rich edit controls placed on forms at design time are instantiated automatically. To add a rich edit control to a form at runtime, instantiate a descendant of TCustomRichEdit such as TRichEdit.

Pass a single Component as a parameter to provide the rich edit control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the rich edit control in a non-VCL window. This syntax is used when the rich edit control is implemented as an ActiveX control that is embedded in a non-VCL window.

TCustomRichEdit overrides the parent object’s constructor to allocate helper objects that manage the rich text attributes of the text.


TCustomRichEdit::TCustomRichEdit
TCustomRichEdit::CreateParams

TCustomRichEdit	See also

Initializes a window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it passes to CreateWindowHandle. TCustomRichEdit overrides the inherited method to specify a Windows rich edit control.


TCustomRichEdit::TCustomRichEdit
TCustomRichEdit::CreateWnd

TCustomRichEdit	See also

Creates a Windows control corresponding to the edit control.

virtual void __fastcall CreateWnd(void);

Description

The CreateWnd method is called when the rich edit control is created, and whenever a change to the rich edit control requires the window to be recreated. CreateWnd first calls the inherited CreateWnd, and then sends the newly created window messages to request notification of Windows events, and, if the window is being recreated, reloads the rich text from a memory stream.


TCustomRichEdit::~TCustomRichEdit

TCustomRichEdit	See also

Destroys an instance of TCustomRichEdit.

__fastcall virtual ~TCustomRichEdit(void);

Description

Do not call ~TCustomRichEdit directly in an application. Instead, use the delete keyword, which takes an indirect reference to the rich edit control.

~TCustomRichEdit destroys all the helper objects that were allocated to manage the rich text, before calling the parent object’s destructor.


TCustomRichEdit::~TCustomRichEdit
TCustomRichEdit::DestroyWnd

TCustomRichEdit	See also

Destroys the rich edit control’s window.

virtual void __fastcall DestroyWnd(void);

Description

DestroyWnd is called automatically when the rich edit control is destroyed or when its window must be temporarily destroyed and recreated to implement a property change. Before the window is destroyed, DestroyWnd saves a copy of the control's text in a memory stream, frees any device contexts, and finally calls DestroyWindowHandle.


TCustomRichEdit::DoSetMaxLength

TCustomRichEdit	See also

Sets the MaxLength property.

virtual void __fastcall DoSetMaxLength(int Value);

Description

DoSetMaxLength overrides the inherited method to implement the MaxLength property for a rich edit window. DoSetMaxLength sends an EM_EXLIMITTEXT message to the window of the rich edit control.


TCustomRichEdit::FindText

TCustomRichEdit	See also 	Example

Searches a given range in the text for a target string.

enum TSearchType { stWholeWord, stMatchCase };

typedef Set<TSearchType, stWholeWord, stMatchCase> TSearchTypes;

int __fastcall FindText(const System::AnsiString SearchStr, int StartPos, int Length, TSearchTypes Options);

Description

Use FindText to search a range of text in a rich edit control for the string specified by the SearchStr parameter. Only the text in the range starting at the position StartPos and continuing through the next Length positions will be searched. Use Options to specify whether the search should match whole words only and whether the search should be case sensitive.  FindText returns the position of the search string, where 0 is the position of the first character in the rich edit control (as opposed to the first position in the search range).  If the search string does not appear in the indicated range, FindText returns -1.

Use FindText rather than programmatically searching through the text of the control, to keep from being thrown off by the encoding of rich text characteristics.


TCustomRichEdit::GetSelLength

TCustomRichEdit	See also

Returns the SelLength property.

virtual int __fastcall GetSelLength(void);

Description

GetSelLength overrides the inherited method to implement the SelLength property for a rich edit window. GetSelLength sends an EM_EXGETSEL message to the window of the edit control and returns the difference between the starting position and the ending position.


TCustomRichEdit::GetSelStart

TCustomRichEdit	See also

Returns the SelStart property.

virtual int __fastcall GetSelStart(void);

Description

GetSelStart overrides the inherited method to implement the SelStart property for a rich edit window. GetSelLength sends an EM_EXGETSEL message to the window of the edit control and returns the starting position.


TCustomRichEdit::GetSelText

TCustomRichEdit	See also

Returns the SelText property.

virtual System::AnsiString __fastcall GetSelText();

Description

GetSelText overrides the inherited method to implement the SelText property for a rich edit window. GetSelText sends an EM_GETSELTEXT message to the window of the rich edit control.


TCustomRichEdit::GetSelTextBuf

TCustomRichEdit	See also

Copies the selected text into a buffer and returns the number of characters copied.

virtual int __fastcall GetSelTextBuf(char * Buffer, int BufSize);

Description

Use GetSelTextBuf to copy the selected text into a character buffer. If there is no selection, the buffer receives an empty string. If the selection contains more than (BufSize - 1) characters, only the first (BufSize - 1) characters are copied. GetSelTextBuf returns the number of characters that were actually copied into the buffer.


TCustomRichEdit::Print

TCustomRichEdit	See also	Example

Formats and prints the contents of the rich edit control.

virtual void __fastcall Print(const System::AnsiString Caption);

Description

Use Print to print the contents of a rich edit control. The Caption parameter specifies the title that appears on the printed output.


TCustomRichEdit::RegisterConversionFormat

TCustomRichEdit	See also

Registers an association between a file extension and a TConversion object that can convert between the native file format and rich text format (RTF).

static void __fastcall RegisterConversionFormat(System::TMetaClass* vmt, const System::AnsiString AExtension, System::TMetaClass* AConversionClass);

Description

Rich edit controls encode text attributes in RTF format. To read from or write to files that encode text attributes in some other format, a converter is required. The converter is a descendant of TConversion that translates between the native file format and RTF when the text is streamed in or out. RegisterConversionFormat sets up an association between a file extension and a converter, so that all attempts to stream between a file with that extension and a rich edit control automatically invoke the appropriate converter.

Note:	Use the Lines property to stream the text to or from a file.


TCustomRichEdit::RequestSize

TCustomRichEdit	See also

Responds to messages from Windows when the text has grown either smaller or larger than the window size.

virtual void __fastcall RequestSize(const Windows::TRect &Rect);

Description

RequestSize merely calls the OnResizeRequest event handler. RequestSize is exposed as a protected method so that derived classes can change the response to Windows messages about an impending window resize. When overriding RequestSize, include a call to the OnResizeRequest event handler.


TCustomRichEdit::SelectionChange

TCustomRichEdit	See also

Responds to messages from Windows that the selection has changed.

DYNAMIC void __fastcall SelectionChange(void);

Description

SelectionChange merely calls the OnSelectionChange event handler. SelectionChange is exposed as a protected method so that derived classes can change the response to Windows messages about selection changes. When overriding SelectionChange, include a call to the OnSelectionChange event handler.


TCustomRichEdit::SetSelLength

TCustomRichEdit	See also

Sets the SelLength property.

virtual void __fastcall SetSelLength(int Value);

Description

SetSelLength overrides the inherited method to implement the SelLength property for a rich edit window. SetSelLength sends an EM_EXSETSEL message to the window of the edit control, specifying a selection that begins at SelStart and ends at SelStart + Value.


TCustomRichEdit::SetSelStart

TCustomRichEdit	See also

Returns the SelStart property.

virtual void __fastcall SetSelStart(int Value);

Description

SetSelStart overrides the inherited method to implement the SelStart property for a rich edit window. SetSelLength sends an EM_EXSETSEL message to the window of the edit control to position the cursor on the position indicated by Value.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMemo


TCustomSocket

Hierarchy	Properties	Methods	Events	See also

TCustomSocket is a base class for socket components.

Unit

scktcomp

Description

Override TCustomSocket to create a socket component that can be assigned event handlers for the events and error conditions that occur. In addition to the properties and methods introduced by TAbstractSocket that enable an application to work with Windows sockets, TCustomSocket introduces several events that can be used by applications.

Do not create instances of TCustomSocket. Use a descendant of TCustomSocket to add the ability to communicate with other machines using TCP/IP. To create a socket that initiates the connection with another machine, use TClientSocket. To create a socket that responds to requests for connections from other machines, use TServerSocket. To create a socket that responds to database requests from other machines and translates them into COM invocations, use TSocketDispatcher.


TCustomSocket properties

TCustomSocket	Alphabetically	Legend

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomSocket properties

TCustomSocket	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomSocket events

TCustomSocket	Alphabetically	Legend

In TCustomSocket

OnAccept

OnConnect

OnConnecting

OnDisconnect

OnError

OnListen

OnLookup

OnRead

OnWrite


TCustomSocket events

TCustomSocket	By object	Legend

OnAccept

OnConnect

OnConnecting

OnDisconnect

OnError

OnListen

OnLookup

OnRead

OnWrite


TCustomSocket::OnAccept

TCustomSocket	See also

Occurs on server sockets just after the connection to a client socket is accepted.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnAccept = {read=FOnAccept, write=FOnAccept};

Description

Write an OnAccept event handler for a server socket to take specific action after the connection to a client socket has been accepted. This is the first point when information is available about the local port and IP address that will be used in the server endpoint of the connection. The port number, and possibly the IP address, will differ from those of the listening socket.

Server sockets open a socket connection for listening to establish a queue to hold client requests. After a request from the queue is accepted by the server socket, an OnAccept event occurs. After the server socket accepts the connection, the client socket completes the connection, and an OnConnect event occurs for the client socket.

The Sender parameter is the server socket component that accepts the connection. The Socket parameter is the TCustomWinSocket object that describes the server endpoint of the connection to the client socket that is about to form.


TCustomSocket::OnConnect

TCustomSocket	See also

Occurs on client sockets just after the connection to the server is opened.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnConnect = {read=FOnConnect, write=FOnConnect};

Description

Write an OnConnect event handler for a client socket to take specific action after the connection to a server socket has been established. Depending on the service, this may be the point when the socket should start reading or writing over the connection.

When a client socket opens a connection, the following events occur:

1	An OnLookup event occurs prior to an attempt to locate the server socket.

2	The Windows socket is set up, and initialized for event notification.

3	An OnConnecting event occurs after the server socket is located.

4	The connection request is accepted by the server and completed by the client socket.

5	An OnConnect event occurs after the connection is established.

The Sender parameter is the client socket component that initiates the connection. The Socket parameter is the TCustomWinSocket object that describes the client endpoint of the newly formed connection.


TCustomSocket::OnConnecting

TCustomSocket	See also

Occurs for a client socket after the server socket has been located, but before the connection is established.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnConnecting = {read=FOnConnecting, write=FOnConnecting};

Description

Write an OnConnecting event handler for a client socket to take specific action just before the connection to a server socket is established. This is the first opportunity to obtain the actual port and IP address of the server endpoint of the connection that is about to form.

When a client socket opens a connection, the following events occur:

1	An OnLookup event occurs prior to an attempt to locate the server socket.

2	The Windows socket is set up, and initialized for event notification.

3	An OnConnecting event occurs after the server socket is located.

4	The connection request is accepted by the server and completed by the client socket.

5	An OnConnect event occurs after the connection is established.

The Sender parameter is the client socket component that initiates the connection. The Socket parameter is the TCustomWinSocket object that describes the server endpoint of the connection that is about to form.


TCustomSocket::OnDisconnect

TCustomSocket	See also

Occurs just before a client socket closes the connection to a server socket.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnDisconnect = {read=FOnDisconnect, write=FOnDisconnect};

Description

Write an OnDisconnect event handler to take specific action when the connection to a server socket is about to be terminated. OnDisconnect occurs after the value of the Active property is set to false, but before the actual connection is closed.

The Sender parameter is the client socket component. The Socket parameter is the TCustomWinSocket object that describes the client endpoint of the connection that is about to end.


TCustomSocket::OnError

TCustomSocket	See also

Occurs when the socket fails in making, using, or shutting down a connection.

enum TErrorEvent { eeGeneral, eeSend, eeReceive, eeConnect, eeDisconnect, eeAccept };

typedef void __fastcall (__closure *TSocketErrorEvent)(System::TObject* Sender, TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode);

__property TSocketErrorEvent OnError = {read=FOnError, write=FOnError};

Description

Write an OnError event handler to respond to errors that arise with the socket connection. Set the ErrorCode parameter to 0 if the OnError event handler successfully deals with the error condition, to prevent an ESocketError from being thrown.

The Sender parameter is the socket component. The Socket parameter is the TCustomWinSocket object that describes the local endpoint of the connection that gave rise to the error. The ErrorCode parameter is the error code returned by the Windows socket API call. The ErrorEvent parameter indicates what Socket was attempting to do when the error occurred. It has one of the following values:

Value	Meaning

eeGeneral	The socket received an error message that does not fit into any of the following categories.

eeSend	An error occurred when trying to write to the socket connection.

eeReceive	An error occurred when trying to read from the socket connection.

eeConnect	For client sockets, this indicates that the client socket can’t locate the server, or that a problem on the server prevents the opening of a connection. For server sockets, this indicates that a client connection request that has already been accepted could not be completed.

eeDisconnect	An error occurred when trying to close a connection.

eeAccept	For server sockets only, this indicates that a problem occurred when trying to accept a client connection request.


TCustomSocket::OnListen

TCustomSocket	See also

Occurs just before a server socket is opened for listening.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnListen = {read=FOnListen, write=FOnListen};

Description

Write an OnListen event handler for a server socket to take specific action just before the socket is opened for listening. OnListen occurs after Address and Port have been bound to the socket connection, but before it is opened. This is the last opportunity to make changes to the socket endpoint before it is opened for listening. Use the SocketHandle property of the Socket parameter for Windows API calls that change the socket.

Server sockets open a socket connection for listening to establish a queue to hold client requests. The connection to a client socket is completed when a request from the queue is accepted.

The Sender parameter is the socket component that listens using the connection. The Socket parameter is the TCustomWinSocket object that describes the server endpoint of the listening connection that is about to open.


TCustomSocket::OnLookup

TCustomSocket	See also

Occurs when a client socket is about to look up the server socket with which it wants to connect.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnLookup = {read=FOnLookup, write=FOnLookup};

Description

Write an OnLookup event handler for a client socket to take specific action just before attempting to locate a server socket. This is the first opportunity to make Windows API calls that affect the client properties of the socket, such as specifying a particular port number. Use the SocketHandle property of the Socket parameter for Windows API calls.

When a client socket opens a connection, the following events occur:

1	An OnLookup event occurs prior to an attempt to locate the server socket.

2	The Windows socket is set up, and initialized for event notification.

3	An OnConnecting event occurs after the server socket is located.

4	The connection request is accepted by the server and completed by the client socket.

5	An OnConnect event occurs after the connection is established.

The Sender parameter is the client socket component that initiates the connection. The Socket parameter is the TCustomWinSocket object that describes the client endpoint of the connection that will be formed with the server.

Note:	Changing the Address, Host, Port, or Service properties of the Sender parameter in an OnLookup event handler will have no effect on the address or port used to locate a server socket. These properties must be correct before the Open method is called.


TCustomSocket::OnRead

TCustomSocket	See also

Occurs when a client socket should read information from the socket connection.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnRead = {read=FOnRead, write=FOnRead};

Description

Write an OnRead event handler to read from the socket connection. The Sender parameter is the client socket component that initiated the connection. The Socket parameter is the TCustomWinSocket object that describes the client endpoint of the socket connection. If the socket is a blocking socket, use a TWinSocketStream object to read from the connection. Otherwise, use the methods of the Socket parameter to perform the actual reading.


TCustomSocket::OnWrite

TCustomSocket	See also

Occurs when a client socket should write information to the socket connection.

typedef void __fastcall (__closure *TSocketNotifyEvent)(System::TObject* Sender, TCustomWinSocket* Socket);

__property TSocketNotifyEvent OnWrite = {read=FOnWrite, write=FOnWrite};

Description

Write an OnWrite event handler to write to the socket connection. The Sender parameter is the client socket component that initiated the connection. The Socket parameter is the TCustomWinSocket object that describes the client endpoint of the socket connection. If the socket is a blocking socket, use a TWinSocketStream object to write to the connection. Otherwise, use the methods of the Socket parameter to perform the actual writing.


TCustomSocket methods

TCustomSocket	Alphabetically	Legend

In TCustomSocket

~TCustomSocket

Error

Event

TCustomSocket

Derived from TAbstractSocket

Close

Open

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomSocket methods

TCustomSocket	By object	Legend

~TCustomSocket

AfterConstruction

Assign

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

DefaultHandler

DestroyComponents

Destroying

Dispatch

Error

Event

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

SafeCallException

TCustomSocket


TCustomSocket::Error

TCustomSocket	See also

Generates an OnError event.

enum TErrorEvent { eeGeneral, eeSend, eeReceive, eeConnect, eeDisconnect, eeAccept };

virtual void __fastcall Error(TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode);

Description

Applications cannot call Error. It responds to error conditions by calling the OnError event handler if it is assigned. Override Error to add class-specific error processing or to block the OnError event.

The Socket parameter indicates the Windows socket object which encounters the error condition.

The ErrorEvent parameter indicates what the socket was trying to do when the error occurred. It has one of the following values:

Value	Meaning

eeGeneral	The socket received an error message that does not fit into any of the following categories.

eeSend	An error occurred when trying to write to the socket connection.

eeReceive	An error occurred when trying to read from the socket connection.

eeConnect	For client sockets, this indicates that the client socket can’t locate the server, or that a problem on the server prevents the opening of a connection. For server sockets, this indicates that a client connection request that has already been accepted could not be completed.

eeDisconnect	An error occurred when trying to close a connection.

eeAccept	For server sockets only, this indicates that a problem occurred when trying to accept a client connection request.

The ErrorCode parameter is the error code received by the Windows socket object. Setting this value to 0 in the Error method prevents the socket from raising an exception. For information on possible error codes, see the Microsoft documentation on Windows sockets.


TCustomSocket::Event

TCustomSocket	See also

Dispatches the events that occur in the normal operation of the socket to the appropriate event handlers.

enum TSocketEvent { seLookup, seConnecting, seConnect, seDisconnect, seListen, seAccept, seWrite, seRead};

virtual void __fastcall Event(TCustomWinSocket* Socket, TSocketEvent SocketEvent);

Description

Applications cannot call Event. It is called automatically when various events occur. Override Event to introduce class-specific responses when certain events occur or to prevent the socket from calling the associated event handler.

The Socket parameter indicates the Windows socket object that calls Event to indicate when specific events occur.

The SocketEvent parameter indicates the event that occurred. It has one of the following values:

Value	Meaning

seLookup	(client sockets only) The Windows socket object is about to locate the server socket. Changing the properties of the client socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will affect the attempted connection.

seConnecting	(client sockets only) The server socket has been located but the connection isn’t completed. This is the first opportunity to obtain the actual server port and IP address used for the connection, which may differ from those of the listening socket contacted initially.

seConnect	The socket connection has just been established. This is the point when a socket starts reading or writing over the connection.

seListen	(server sockets only) The Windows socket object has been initialized and is about to open a listening connection. Changing the properties of the server socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will the listening connection.

seAccept	(server sockets only) A client connection request has just been accepted. This is the first opportunity to obtain the port and IP address of the individual client connection.

seWrite	The socket is ready for information to be written.

seRead	The socket is receiving information from a socket on the other end of the connection.


TCustomSocket::TCustomSocket

TCustomSocket

Creates a new TCustomSocket object.

__fastcall virtual TCustomSocket(Classes::TComponent* AOwner) : Scktcomp::TAbstractSocket(AOwner) { }

Description

Do not create instances of TCustomSocket. TCustomSocket includes pure virtual methods that must be overriden by a descendant.


TCustomSocket::~TCustomSocket

TCustomSocket

~TCustomSocket frees the memory associated with the TCustomSocket object.

__fastcall virtual ~TCustomSocket(void) { }

Description

Do not call ~TCustomSocket directly. Instead, use the delete keyword on the object, which causes ~TCustomSocket to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TAbstractSocket


TCustomTabControl

Hierarchy	Properties	Methods	Events	See also

TCustomTabControl is the base type for tab-control components such as TTabControl and TPageControl.

Unit

comctrls

Description

Use TCustomTabControl as a base class when defining a control that includes a set of notebook style tabs across the top. TCustomTabControl introduces many properties, methods, and events to manage appearance and behavior of the tabs, and to respond when the user selects one of the tabs.


TCustomTabControl properties

TCustomTabControl	Alphabetically	Legend

In TCustomTabControl

DisplayRect

HotTrack

MultiLine

ScrollOpposite

TabHeight

TabIndex

TabPosition

Tabs

TabWidth

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomTabControl properties

TCustomTabControl	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DisplayRect

Enabled

Handle

Height

HelpContext

Hint

HotTrack

Left

MultiLine

Name

Owner

Parent

ParentWindow

ScrollOpposite

ShowHint

Showing

TabHeight

TabIndex

TabOrder

TabPosition

Tabs

TabStop

TabWidth

Tag

Top

VCLComObject

Visible

Width

WindowProc


TCustomTabControl::DisplayRect

TCustomTabControl	See also

Specifies the bounding rectangle of a tab control client area.

__property Windows::TRect DisplayRect = {read=GetDisplayRect};

Description

Use DisplayRect to obtain the coordinates, in pixels, of the portion of the tab control that represents the contents of the tab pages. The appearance of this portion of the tab control does not change when different tabs are selected.

Use DisplayRect rather than the ClientRect property to determine the portion of the tab control that can contain other objects.


TCustomTabControl::HotTrack

TCustomTabControl	See also

Determines whether labels on the tab under the mouse are automatically highlighted.

__property bool HotTrack = {read=FHotTrack, write=SetHotTrack, default=0};

Description

Set HotTrack to true to provide visual feedback to the user about which tab would be selected if the mouse button is clicked. HotTrack is especially useful when the tab control contains multiple rows of tabs.


TCustomTabControl::MultiLine

TCustomTabControl	See also	Example

Determines whether the tabs can appear on more than one row.

__property bool MultiLine = {read=FMultiLine, write=SetMultiLine, default=0};

Description

Use MultiLine to determine how the tabs are displayed. If MultiLine is true, the tabs are displayed on more than one row when the number of tabs exceeds the number that fits across the top of the tab control. How many rows is determined by how many tabs are in the tab control. If MultiLine is false, the tabs are displayed on one row only, and the user must scroll the displayed scroll arrows to view all the tabs.


TCustomTabControl::ScrollOpposite

TCustomTabControl	See also

Determines how the rows of tabs are scrolled in a muli-line tab control.

__property bool ScrollOpposite = {read=FScrollOpposite, write=SetScrollOpposite, default=0};

Description

Set ScrollOpposite to determine where previous rows of tabs in a multi-line tab control move when the user selects a tab in another row. When ScrollOpposite is true, previous rows of tabs are moved to the bottom of the tab control if TabPosition is tpTop, or to the top if TabPosition is tpBottom. When ScrollOpposite is false, previous rows of tabs are moved to the back of all other rows of tabs.

For example, in a tab control with three rows of tabs at the top, if the user selects a tab in the second row, ScrollOpposite determines where the first row moves. If ScrollOpposite is true, the second row now appears at the front (bottom) row on top of the tab control, followed by the third row behind (above) it. The first row moves to the bottom of the tab control. If ScrollOpposite is false, the first row moves to the back (top), so that the tab control displays the second row in front (at the bottom of the tab region), followed by the third row (now in the middle), followed by the first row.

Note:	Setting ScrollOpposite to true automatically sets the MultiLine property to true.


TCustomTabControl::TabHeight

TCustomTabControl	See also	Example

Specifies the height, in pixels, of the tabs in the tab control.

__property short TabHeight = {read=FTabSize.y, write=SetTabHeight, default=0};

Description

Set TabHeight to control the height of the tabs that appear above the client region of the tab control. The TabHeight property is the vertical size in pixels of the individual tabs. If TabHeight is set to 0, the tabs automatically size themselves to fit their text.


TCustomTabControl::TabIndex

TCustomTabControl	See also

Identifies the selected tab on a tab control.

__property int TabIndex = {read=GetTabIndex, write=SetTabIndex, default=-1};

Description

Read TabIndex to determine which tab was selected by the user. TabIndex is the index of the tab in the list of labels maintained by the Tabs property. The first (leftmost) tab has a TabIndex of 0, the next has 1, and so on. If no tabs are selected, TabIndex has a value of -1.

Set TabIndex to programmatically change the selected tab in the tab control.


TCustomTabControl::TabPosition

TCustomTabControl	See also

Determines whether tabs appear at the top or bottom.

enum TTabPosition { tpTop, tpBottom };

__property TTabPosition TabPosition = {read=FTabPosition, write=SetTabPosition, default=0};

Description

Set TabPosition to tpTop to display the tabs at the top of the tab control. Set TabPosition to tpBottom to display the tabs at the bottom. If the ScrollOpposite property is true, tabs can appear at both top and bottom, with the row containing the current tab and all subsequent rows on the side indicated by TabPosition.


TCustomTabControl::Tabs

TCustomTabControl	See also	Example

Contains the list of text strings that label the tabs of the tab control.

__property Classes::TStrings* Tabs = {read=FTabs, write=SetTabs};

Description

Use Tabs to access the labels of the tabs in the tab control, or any objects associated with those tabs using the Objects property of the Tabs object. Add new strings to the Tabs property to add new tabs to the tab control. Rearrange the Tabs list to rearrange the tabs in the tab control.


TCustomTabControl::TabWidth

TCustomTabControl	See also	Example

Specifies the horizontal size, in pixels, of the tabs in the tab control.

__property short TabWidth = {read=FTabSize.x, write=SetTabWidth, default=0};

Description

Set TabWidth to control the width of the tabs that appear above the client region of the tab control. The TabWidth property is the horizontal size in pixels of the individual tabs. If TabWidth is set to 0, the tabs automatically size themselves to fit their text.


TCustomTabControl events

TCustomTabControl	Alphabetically	Legend

In TCustomTabControl

OnChange

OnChanging


TCustomTabControl events

TCustomTabControl	By object	Legend

OnChange

OnChanging


TCustomTabControl::OnChange

TCustomTabControl	See also	Example

Occurs after a new tab is selected.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action immediately after the selected tab changes. Use the TabIndex property to determine which tab is now selected. This is the opportunity to make any changes to the control that reflect the new state implied by the selected tag.

Before the value of TabIndex changes, an OnChanging event occurs.


TCustomTabControl::OnChanging

TCustomTabControl	See also	Example

Occurs immediately before a new tab is selected.

typedef void __fastcall (__closure *TTabChangingEvent)(System::TObject* Sender, bool &AllowChange);

__property TTabChangingEvent OnChanging = {read=FOnChanging, write=FOnChanging};

Description

Write an OnChanging event handler to take specific action immediately before the selected tab changes. Set the AllowChange parameter to false to prevent the change.

Use an OnChanging event handler to prevent the user from leaving a tab setting until certain conditions have been met. An OnChanging event handler can also be used to save information about the current state of the tab control before it is changed by a new tab selection.


TCustomTabControl methods

TCustomTabControl	Alphabetically	Legend

In TCustomTabControl

~TCustomTabControl

AlignControls

CanChange

CanShowTab

Change

CreateParams

CreateWnd

DestroyWnd

TCustomTabControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomTabControl methods

TCustomTabControl	By object	Legend

~TCustomTabControl

AlignControls

Assign

BeginDrag

BringToFront

Broadcast

CanChange

CanFocus

CanShowTab

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CreateParams

CreateWnd

DefaultHandler

DestroyComponents

Destroying

DestroyWnd

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomTabControl

Update

UpdateControlState


TCustomTabControl::AlignControls

TCustomTabControl	See also

Aligns the controls contained in the tab control.

virtual void __fastcall AlignControls(Controls::TControl* AControl, Windows::TRect &Rect);

Description

Call AlignControls to align any child controls within the client area of the tab control. AlignControls uses the Align property value of each child control to determine how to align it. The AControl parameter can be NULL. If AControl is not NULL, that control takes precedence in alignment over other, similarly-aligned controls.

AlignControls overrides the parent class’s method to use the value of DisplayRect for the Rect parameter.


TCustomTabControl::CanChange

TCustomTabControl	See also

Determines whether the selected tab can be changed.

DYNAMIC bool __fastcall CanChange(void);

Description

CanChange is called automatically when an attempt is made to change the selected tab. CanChange generates an OnChanging event so that an OnChanging event handler can prevent the selection from changing. If there is no OnChanging event handler, CanChange returns true, allowing the change.

Override CanChange to specify additional processing before the OnChanging event handler executes or to block the OnChanging event.


TCustomTabControl::CanShowTab

TCustomTabControl	See also

Indicates whether the tab can be selected.

virtual bool __fastcall CanShowTab(int TabIndex);

Description

Call CanShowTab to determine whether a tab can be selected or accessed. CanShowTab is exposed as a protected method so that descendants can override this method to provide application-specific criteria that determines whether a tab is accessible.

TabIndex is the index of the tab in the list of labels maintained by the Tabs property.

CanShowTab returns a Boolean value that indicates whether the tab specified in TabIndex can be accessed.

Tip:	CanShowTab can be used with such methods as TWinControl::CanFocus, to determine whether the tab can both be accessed and can receive focus. Criteria for an overridden CanShowTab might include checking whether the tab is enabled.


TCustomTabControl::Change

TCustomTabControl	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(void);

Description

Change is called automatically when the selected tab changes. Override Change to specify additional processing before the OnChange event handler executes, or to block the OnChange event.


TCustomTabControl::TCustomTabControl

TCustomTabControl	See also

Creates and initializes an instance of TCustomTabControl.

__fastcall virtual TCustomTabControl(Classes::TComponent* AOwner);

__fastcall TCustomTabControl(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not create instances of TCustomTabControl. It is intended for use only as a base class. Instead, create TCustomTabControl descendants such as TPageControl or TTabControl.

TCustomTabControl takes single Component as a parameter to provide the tab control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. TCustomTabControl takes a window handle as a parameter to embed the tab control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TCustomTabControl calls the parent object’s constructor and sets the initial values for the tab control, including the creation of a tab list that contains the text strings for the tabs.


TCustomTabControl::TCustomTabControl
TCustomTabControl::CreateParams

TCustomTabControl	See also

Sets up the window-creation parameters for the tab control.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

Tab controls call CreateParams internally when the window for the tab control must be generated. CreateParams overrides the parent class’s method to specify a tab control window with the current property settings.


TCustomTabControl::TCustomTabControl
TCustomTabControl::CreateWnd

TCustomTabControl	See also

Creates the window for a tab control.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd is called automatically when the tab control’s window is recreated. CreateWnd calls the parent class’s method, before assigning any saved tab text strings in internal storage.


TCustomTabControl::~TCustomTabControl

TCustomTabControl	See also

Destroys an instance of TCustomTabControl.

__fastcall virtual ~TCustomTabControl(void);

Description

Do not call ~TCustomTabControl directly in an application. Instead, use the delete keyword. ~TCustomTabControl frees the tab list that holds the list of text strings for the tabs and calls the parent class’s destructor.


TCustomTabControl::~TCustomTabControl
TCustomTabControl::DestroyWnd

TCustomTabControl	See also

Destroys the window used by the tab control.

virtual void __fastcall DestroyWnd(void);

Description

DestroyWnd is called automatically when the tab control is destroyed or when its window needs to be recreated. DestroyWnd saves a copy of the tab text strings in internal storage before calling the inherited method.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomTreeView

Hierarchy	Properties	Methods	Events	See also

TCustomTreeView is the abstract base type for tree-view components such as TTreeView.

Unit

comctrls

Description

Use TCustomTreeView as a base class when defining components that present information in a hierarchical structure with nodes that can be expanded or collapsed. Most of the properties defined in TCustomTreeView are protected so that you can choose whether to publish them in your own tree view components.

Do not create instances of TCustomTreeView. To add a tree view control to a form, use TTreeView.


TCustomTreeView properties

TCustomTreeView	Alphabetically	Legend

In TCustomTreeView

BorderStyle

DragMode

DropTarget

HideSelection

Images

Indent

Items

ReadOnly

RightClickSelect

Selected

ShowButtons

ShowLines

ShowRoot

SortType

StateImages

TopItem

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomTreeView properties

TCustomTreeView	By object	Legend

Align

BorderStyle

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DragMode

DropTarget

Enabled

Handle

Height

HelpContext

HideSelection

Hint

Images

Indent

Items

Left

Name

Owner

Parent

ParentWindow

ReadOnly

RightClickSelect

Selected

ShowButtons

ShowHint

Showing

ShowLines

ShowRoot

SortType

StateImages

TabOrder

TabStop

Tag

Top

TopItem

VCLComObject

Visible

Width

WindowProc


TCustomTreeView::BorderStyle

TCustomTreeView	See also

Determines whether the tree view control has a border.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Set BorderStyle to specify whether the tree view control should be outlined with a single-line border. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border


TCustomTreeView::DragMode

TCustomTreeView	See also

Determines whether drag and drop occurs automatically.

__property DragMode;

Description

Use the DragMode property to control when the user is able to drag the items in the tree view. Disable the drag and drop capability at runtime by changing the DragMode property value to dmManual.

These are the possible values:

Value	Meaning

dmAutomatic	If dmAutomatic is selected, the tree view automatically allows items to be dragged; the user just clicks and drags them.

dmManual	If dmManual is selected, items can't be dragged until the application calls the BeginDrag method.


TCustomTreeView::DropTarget

TCustomTreeView	See also

Specifies which item in the tree view appears as the target of a drag and drop operation.

__property TTreeNode* DropTarget = {read=GetDropTarget, write=SetDropTarget};

Description

Read DropTarget to determine whether a node in the tree view is drawn as the target of a drag and drop operation. Set DropTarget when specifying a particular node in the tree view as the drop target of a dragged item.

Note:	When DropTarget is set, the application must still handle the actual logic of accepting the dragged object by the indicated node.


TCustomTreeView::HideSelection

TCustomTreeView	See also

Determines whether a selected node appears selected when the focus shifts to another control.

__property bool HideSelection = {read=FHideSelection, write=SetHideSelection, default=1};

Description

Use HideSelection to specify whether the user is given visual feedback about the current selection in the tree view when it does not have focus. If true, the selected node is not visually distinct from other nodes until focus returns to the control. If false, the node always appears selected.


TCustomTreeView::Images

TCustomTreeView	See also	Example

Determines which image list is associated with the tree view.

__property Controls::TImageList* Images = {read=FImages, write=SetImages};

Description

Use Images to provide a customized list of bitmaps that can be displayed to the left of a node’s label. Individual nodes specify the image from this list that should appear by setting their ImageIndex property.


TCustomTreeView::Indent

TCustomTreeView	See also

Specifies the amount of indentation in pixels when a list of child nodes is expanded.

__property int Indent = {read=FIndent, write=SetIndent, default=0};

Description

Use Indent to determine how far child nodes are indented from their parent nodes when the parent is expanded.


TCustomTreeView::Items

TCustomTreeView	See also 	Example

Lists the individual nodes that appear in the tree view control.

__property TTreeNodes* Items = {read=FTreeNodes, write=SetTreeNodes};

Description

Individual nodes in a tree view are TTreeNode objects. These individual nodes can be accessed by using the Items property along with the item's index into the tree view. For example, to access the second item in the tree view, you could use the following code.

When setting this property at design-time in the Object Inspector the TreeView Items Editor appears. Use the New Item and New SubItem buttons to add items to the tree view. Use the Text property to modify what text is displayed in the label of the item.

At run-time nodes can be added and inserted by using the TTreeNodes methods AddChildFirst, AddChild, AddChildObjectFirst, AddChildObject, AddFirst, Add, AddObjectFirst, AddObject, and Insert.

Note:	Accessing tree view items by index can be time-intensive, particularly when the tree view contains many items. For optimal performance, try to design your application so that it has as few dependencies on the tree view’s item index as possible.


TCustomTreeView::ReadOnly

TCustomTreeView	See also

Determines whether the user can edit the node labels.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, default=0};

Description

Use ReadOnly to specify whether the user can edit the nodes of the tree view. If ReadOnly is true, the user can expand and collapse nodes, but can’t edit their labels. If ReadOnly is false, the user can edit the labels as well. The default value is false.


TCustomTreeView::RightClickSelect

TCustomTreeView	See also

Determines whether the Selected property returns nodes that are selected using the right mouse button.

__property bool RightClickSelect = {read=FRightClickSelect, write=FRightClickSelect, default=0};

Description

Use RightClickSelect to allow the Selected property to indicate nodes the user clicks with the right mouse button.  If RightClickSelect is true, the value of Selected is the value of the node last clicked with either the right or left mouse button.  If RightClickSelect is false, the value of Selected is the node last clicked using the left mouse button.

RightClickSelect affects only the value of the Selected property.  It does not cause the tree view to highlight a new node if the node is selected using the right mouse button.

Note:	RightClickSelect must be set to true before the user right-clicks the tree view for it to affect the value of the Selected property.


TCustomTreeView::Selected

TCustomTreeView	See also 	Example

Specifies the selected node in the tree view.

__property TTreeNode* Selected = {read=GetSelection, write=SetSelection};

Description

Read Selected to access the selected node of the tree view. If there is no selected node, the value of Selected is NULL.

Set Selected to set a node in the tree view. When a node becomes selected, the tree view's OnChanging and OnChanged events occur. Also, if the specified node is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified node. In this case, the tree views OnExpanded and OnExpanding events occur as well.

Note:	If the RightClickSelect property is true, the value of Selected is the last node that was clicked in the tree view, even if it was clicked with the right mouse button.  This may differ from the node that is highlighted to indicate selection.


TCustomTreeView::ShowButtons

TCustomTreeView	See also

Specifies whether to display plus (+) and minus (-) buttons to the left side of each parent item.

__property bool ShowButtons = {read=FShowButtons, write=SetButtonStyle, default=1};

Description

If ShowButtons is true, a button will appear to the left of each parent item. The user can click the button to expand or collapse the child items as an alternative to double-clicking the parent item.


TCustomTreeView::ShowLines

TCustomTreeView	See also

Specifies whether to display the lines that link child nodes to their corresponding parent nodes.

__property bool ShowLines = {read=FShowLines, write=SetLineStyle, default=1};

Description

If ShowLines is true, lines linking child nodes to their parent nodes are displayed. Nodes at the root of the hierarchy are not automatically linked. To link nodes at the root, the ShowRoot property must also be set to true.


TCustomTreeView::ShowRoot

TCustomTreeView	See also

Specifies whether lines connecting top-level nodes are displayed.

__property bool ShowRoot = {read=FShowRoot, write=SetRootStyle, default=1};

Description

To show lines connecting top-level nodes to a single root, set the tree view's ShowRoot and ShowLines properties to true.


TCustomTreeView::SortType

TCustomTreeView	See also

Determines if and how the nodes in a tree view are automatically sorted.

__property TSortType SortType = {read=FSortType, write=SetSortType, default=0};

Description

Once a tree view is sorted, the original hierarchy is lost. That is, setting the SortType back to stNone will not restore the original order of items. These are the possible values:

Value	Meaning

stNone	No sorting is done.

stData	The items are sorted when the Data object or SortType is changed.

stText	The items are sorted when the Caption or SortType is changed.

stBoth	The items are sorted when either the Data object, the Caption or SortType is changed

Optionally, the OnCompare event can be hooked to handle comparisons. The OnCompare event will be called to compare two nodes for sorting.


TCustomTreeView::StateImages

TCustomTreeView	See also	Example

Determines which image list to use for state images.

__property Controls::TImageList* StateImages = {read=FStateImages, write=SetStateImages};

Description

Use StateImages to provide a set of bitmaps that reflect the state of tree view nodes. The state image appears as an additional image to the left of the item's icon.


TCustomTreeView::TopItem

TCustomTreeView	See also

Specifies the topmost node that appears in the tree view.

__property TTreeNode* TopItem = {read=GetTopItem, write=SetTopItem};

Description

When TopItem is changed, the tree view scrolls vertically so that the specified node is topmost in the list view.


TCustomTreeView events

TCustomTreeView	Alphabetically	Legend

In TCustomTreeView

OnChange

OnChanging

OnCollapsed

OnCollapsing

OnCompare

OnDeletion

OnEdited

OnEditing

OnExpanded

OnExpanding

OnGetImageIndex

OnGetSelectedIndex


TCustomTreeView events

TCustomTreeView	By object	Legend

OnChange

OnChanging

OnCollapsed

OnCollapsing

OnCompare

OnDeletion

OnEdited

OnEditing

OnExpanded

OnExpanding

OnGetImageIndex

OnGetSelectedIndex


TCustomTreeView::OnChange

TCustomTreeView	See also

Occurs whenever the selection has changed from one node to another.

__property TTVChangedEvent OnChange = {read=FOnChange, write=FOnChange};

Description

The TTVChangedEvent type points to a method that is called when the selection has changed from one item to another (OnChange event). The Node parameter is the node whose selection state has changed.

Note:	The OnChange event does not occur for nodes selected using the right mouse button when RightClickSelect is true.  To respond to changes in the value of the Selected property when RightClickSelect is true, use the OnMouseUp event.


TCustomTreeView::OnChanging

TCustomTreeView	See also

Occurs whenever the selection is about to be changed from one node to another.

__property TTVChangingEvent OnChanging = {read=FOnChanging, write=FOnChanging};

Description

The TTVChangingEvent type points to a method that is called when the selection is about to be changed from one node to another. Set AllowChange to false, to prevent selection from moving to a new node. The Node parameter specifies the currently selected node.


TCustomTreeView::OnCollapsed

TCustomTreeView	See also

Occurs after a node has been collapsed.

__property TTVExpandedEvent OnCollapsed = {read=FOnCollapsed, write=FOnCollapsed};

Description

Write an OnCollapsed event handler to respond after a node in the tree view collapses. The Node parameter is the node whose children are no longer visible.


TCustomTreeView::OnCollapsing

TCustomTreeView	See also

Occurs when a node is about to be collapsed.

__property TTVCollapsingEvent OnCollapsing = {read=FOnCollapsing, write=FOnCollapsing};

Description

The TTVCollapsingEvent type points to a method that is called when a node is about to be collapsed. Set the AllowCollapse parameter to false to prevent the node specified by the Node parameter from being collapsed.


TCustomTreeView::OnCompare

TCustomTreeView	See also

Occurs when two nodes must be compared during a sort of the nodes in the tree view.

__property TTVCompareEvent OnCompare = {read=FOnCompare, write=FOnCompare};

Description

Write an OnCompare event handler to customize the sort order of the nodes in the tree view. Set the Compare parameter to a value less than 0 if Node1 is less than Node2. Set Compare to 0 if Node1 is equivalent to Node2, and set Compare to a value greater than 0 if Node1 is greater than Node2. If an OnCompare event handler is not provided, tree view nodes are sorted alphabetically, based on their labels.


TCustomTreeView::OnDeletion

TCustomTreeView	See also

Occurs when a node in the tree view is deleted.

__property TTVExpandedEvent OnDeletion = {read=FOnDeletion, write=FOnDeletion};

Description

Write an OnDeletion event handler to respond when a node is deleted from the tree view control.


TCustomTreeView::OnEdited

TCustomTreeView	See also

Occurs after the user edits the Text property of a node.

__property TTVEditedEvent OnEdited = {read=FOnEdited, write=FOnEdited};

Description

Write an OnEdited event handler to respond to changes the user makes to the node labels. The Node parameter is the node whose label was edited. The S parameter is the new value of the node’s Text property. The node’s label can be changed in an OnEdited event handler before the user’s edits are committed. This event can occur only if ReadOnly is set to false.


TCustomTreeView::OnEditing

TCustomTreeView	See also

Occurs when the user starts to edit the Text property of a node.

__property TTVEditingEvent OnEditing = {read=FOnEditing, write=FOnEditing};

Description

Write an OnEditing event handler to determine whether the user is allowed to edit the label of a specific node in the tree view. Set the AllowEdit parameter to false to prevent the user from editing the node specified by the Node parameter. To disallow editing of all nodes in the tree view, use the ReadOnly property instead.


TCustomTreeView::OnExpanded

TCustomTreeView	See also

Occurs after a node is expanded.

__property TTVExpandedEvent OnExpanded = {read=FOnExpanded, write=FOnExpanded};

Description

Write an OnExpanded event handler to respond when a node in the tree view is expanded. The Node parameter specifies the node whose children are now displayed to the user.


TCustomTreeView::OnExpanding

TCustomTreeView	See also

Occurs when a node is about to be expanded.

__property TTVExpandingEvent OnExpanding = {read=FOnExpanding, write=FOnExpanding};

Description

Write an OnExpanding event handler to determine whether a node can be expanded. Set the AllowExpansion parameter to false to prevent the node from expanding.


TCustomTreeView::OnGetImageIndex

TCustomTreeView	See also

Occurs when the tree view looks up the ImageIndex of a node.

__property TTVExpandedEvent OnGetImageIndex = {read=FOnGetImageIndex, write=FOnGetImageIndex};

Description

Write an OnGetImageIndex event handler to change the image index for the particular node before it is drawn. For example, the bitmap of a node can be changed to indicate a different state for the node.


TCustomTreeView::OnGetSelectedIndex

TCustomTreeView	See also

Occurs when the tree view looks up the SelectedIndex of a node.

__property TTVExpandedEvent OnGetSelectedIndex = {read=FOnGetSelectedIndex, write=FOnGetSelectedIndex};

Description

Write an OnGetSelectedIndex event handler to change the selected image index of a node before it is drawn.


TCustomTreeView methods

TCustomTreeView	Alphabetically

In TCustomTreeView

~TCustomTreeView

AlphaSort

CustomSort

Delete

FullCollapse

FullExpand

GetHitTestInfoAt

GetImageIndex

GetNodeAt

GetSelectedIndex

IsEditing

LoadFromFile

LoadFromStream

SaveToFile

SaveToStream

TCustomTreeView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomTreeView methods

TCustomTreeView	By object

~TCustomTreeView

AlphaSort

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CustomSort

DefaultHandler

Delete

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

FullCollapse

FullExpand

GetHitTestInfoAt

GetImageIndex

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetNodeAt

GetParentComponent

GetSelectedIndex

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

IsEditing

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

SaveToFile

SaveToStream

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomTreeView

Update

UpdateControlState


TCustomTreeView::AlphaSort

TCustomTreeView	See also

Sorts all nodes alphabetically by label in the tree view control.

bool __fastcall AlphaSort(void);

Description

Call AlphaSort to sort the nodes of the tree view. If successful, AlphaSort returns true. To have the tree view maintain all nodes in a sorted order (for example, when the user edits the labels), use the SortType property.


TCustomTreeView::TCustomTreeView

TCustomTreeView	See also

Creates an instance of a TTreeView control.

__fastcall virtual TCustomTreeView(Classes::TComponent* AOwner);

__fastcall TCustomTreeView(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not call TCustomTreeView directly. To add a tree view control to a form, create an instance of a TCustomTreeView descendant using the new keyword.

Tree view controls placed on forms at design time are created automatically. After calling the parent object’s constructor, TCustomTreeView initializes many properties the control, including setting BorderStyle to bsSingle and setting ShowButtons, ShowRoot, ShowLines, and HideSelection to true.


TCustomTreeView::CustomSort

TCustomTreeView	See also 	Example

Sorts the nodes in the tree view into a customized sort order.

bool __fastcall CustomSort(PFNTVCOMPARE SortProc, int Data);

Description

Use CustomSort to sort the nodes of the tree view where the sort order is defined by the SortProc parameter. The lParam1 and lParam2 parameters of the sort procedure can be cast to TTreeNode objects are compared. The lParamSort parameter of the sort procedure is the value of Data parameter of CustomSort. The sort procedure should return a value less than 0 if lParam1 should come before lParam2, should return 0 if the two values are equivalent, and should return a value greater than 0 if lParam1 should follow lParam2.

If the SortProc parameter is NULL, the default AlphaSort method is called.

Note:	To have the tree view sort all nodes automatically (for example, when the user edits the labels), use the SortType property instead, and provide an OnCompare event handler.


TCustomTreeView::Delete

TCustomTreeView	See also

Deletes::::.

DYNAMIC void __fastcall Delete(TTreeNode* Node);

Description

Call Delete to destroy a single tree node. Delete as implemented does nothing except invoke the handler for the OnDeletion event, if one is assigned. Descendants should override Delete to provide specific tree node destruction functionality. In addition to destroying the tree node, this added functionality might include destroying objects stored in the TTreeNode::Data property.

Node is the tree node to be destroyed.


TCustomTreeView::~TCustomTreeView

TCustomTreeView	See also

Destroys the tree view control and is called by the Delete method.

__fastcall virtual ~TCustomTreeView(void);

Description

Use the Delete method to delete the tree rather than the ~TCustomTreeView method.


TCustomTreeView::FullCollapse

TCustomTreeView	See also

Collapses all the nodes within a tree view control.

void __fastcall FullCollapse(void);

Description

Call FullCollapse to hide all the nodes in the tree view except those at the first level.


TCustomTreeView::FullExpand

TCustomTreeView	See also

Expands all nodes within the tree view control.

void __fastcall FullExpand(void);

Description

Call FullExpand to display all the nodes in the tree view. If ShowButtons is true, all buttons will change from '+' to '-'.


TCustomTreeView::GetHitTestInfoAt

TCustomTreeView	See also 	Example

Returns information about the location of a point relative to the client area of the tree view control.

THitTests __fastcall GetHitTestInfoAt(int X, int Y);

Description

Call GetHitTestInfoAt to determine what portion of the tree view, if any, sits under the point specified by the X and Y parameters. For example, use GetHitTestInfoAt to provide feedback about how to expand or collapse nodes when the mouse is over the relevant portions of the tree view.

GetHitTestInfo returns a THitTests type. Following are the possible return values of GetHitTestInfoAt:

Value	Location of (X,Y)

htAbove	Above the client area of the tree view control.

htBelow	Below the client area of the tree view control.

htNowhere	In the client area of the tree view control but below the last item.

htOnItem	On the bitmap or label associated with an item.

htOnButton	On the button associated with an item.

htOnIcon	On the bitmap associated with an item.

htOnIndent	On the indentation associated with an item.

htOnLabel	On the label (text) associated with an item.

htOnRight	In the area to the right of an item.

htOnStateIcon	On the state icon for a tree view item that is in a user-defined state.

htToRight	To the right of the client area of the tree view control.

htToLeft	To the left of the client area of the tree view control.


TCustomTreeView::GetImageIndex

TCustomTreeView	See also 	Example

Sets the image index for a tree node.

virtual void __fastcall GetImageIndex(TTreeNode* Node);

Description

Call GetImageIndex to set the image index of a tree node. GetImageIndex as implemented does nothing except invoke the handler for the OnGetImageIndex event, if one is assigned. Descendants should override GetImageIndex to provide functionality for setting the tree node’s image index. Such functionality might include conditionally using different images dependent on a context established by the tree view.

Node is the tree node in which the image index is set.


TCustomTreeView::GetNodeAt

TCustomTreeView	See also 	Example

Returns the node that is found at the specified position.

TTreeNode* __fastcall GetNodeAt(int X, int Y);

Description

Call GetNodeAt to access the node at the position specified by the X and Y parameters. X and Y specify the position in pixels relative to the top left corner of the tree view. If there is no node at the location, GetNodeAt returns NULL.


TCustomTreeView::GetSelectedIndex

TCustomTreeView	See also 	Example

Sets the image index for a selected tree node.

virtual void __fastcall GetSelectedIndex(TTreeNode* Node);

Description

Call GetSelectedIndex to set the image index of a tree node when the tree node is selected. GetSelectedIndex as implemented does nothing except invoke the handler for the OnGet GetSelectedIndex event, if one is assigned. Descendants should override GetSelectedIndex to provide functionality for setting the tree node’s image index. Such functionality might include conditionally using different images dependent on a context established by the tree view.

Node is the tree node in which the image index is set.


TCustomTreeView::IsEditing

TCustomTreeView	See also

Indicates whether a node is currently being edited by the user.

bool __fastcall IsEditing(void);

Description

IsEditing returns true if any node label in the tree view is being edited.


TCustomTreeView::LoadFromFile

TCustomTreeView	See also

Reads the file specified in FileName and loads the data into the tree view.

void __fastcall LoadFromFile(const System::AnsiString FileName);

Description

Use the LoadFromFile method to retrieve tree view data from a file and load into a tree view.


TCustomTreeView::LoadFromStream

TCustomTreeView	See also

Reads tree view data from a stream and stores the contents in the tree view.

void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Use LoadFromStream to read the nodes of the tree view from the specified stream. For example, an application can save the information displayed in a tree view as the data in a Binary Large Object (BLOB) field. LoadFromStream can retrieve the data using a TBlobStream object.


TCustomTreeView::SaveToFile

TCustomTreeView	See also

Saves a the tree view to the file specified in FileName.

void __fastcall SaveToFile(const System::AnsiString FileName);

Description

Use the SaveToFile method to store tree view data to a text file. The nodes can later be reloaded from the file into a new tree view object using the LoadFromFile method.


TCustomTreeView::SaveToStream

TCustomTreeView	See also

Writes the data in the tree view to the stream passed as the Stream parameter.

void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Use the SaveToStream method to stream out tree view data. It can be streamed back in to another tree view object using the LoadFromStream method.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomUpDown

Hierarchy	Properties	Methods	Events	See also

TCustomUpDown is the base type for up-down size controls such as TUpDown.

Unit

comctrl

Description

Use TCustomUpDown as a base class when defining up-down controls such as the arrows that appear in a spin box. Up-down controls allow users to change the size of a numerical value by clicking on arrow buttons. TCustomUpDown introduces several properties, events, and methods to associate an up-down control with another control in a form and to communicate the size changes specified by the user.

Do not create instances of TCustomUpDown. To put an up-down control in a form, use TUpDown.


TCustomUpDown properties

TCustomUpDown	Alphabetically	Legend

In TCustomUpDown

AlignButton

ArrowKeys

Associate

Increment

Max

Min

Orientation

Position

Thousands

Wrap

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TCustomUpDown properties

TCustomUpDown	By object	Legend

Align

AlignButton

ArrowKeys

Associate

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Increment

Left

Max

Min

Name

Orientation

Owner

Parent

ParentWindow

Position

ShowHint

Showing

TabOrder

TabStop

Tag

Thousands

Top

VCLComObject

Visible

Width

WindowProc

Wrap


TCustomUpDown::AlignButton

TCustomUpDown	See also

Specifies the position of the up-down control relative to its companion control.

enum TUDAlignButton { udLeft, udRight };

__property TUDAlignButton AlignButton = {read=FAlignButton, write=SetAlignButton, default=1};

Description

Set AlignButton to indicate where to position the up-down control. The up-down control appears attached to the outer edge of the control specified by the Associate property. These are the possible values:

Value	Meaning

udLeft	Position the up-down control on the left edge of the companion control.

udRight	Position the up-down control on the right edge of the companion control.

The up-down control resizes itself to the height of the companion control.


TCustomUpDown::ArrowKeys

TCustomUpDown	See also

Determines whether the up-down control receives input from the Up arrow and Down arrow keys.

__property bool ArrowKeys = {read=FArrowKeys, write=SetArrowKeys, default=1};

Description

Use ArrowKeys to specify whether the up-down control responds to keyboard input. ArrowKeys is used only when the up-down control is associated with a companion control. When ArrowKeys is true, the up-down control responds to the Up arrow and Down arrow keys, even when its companion control has input focus. When ArrowKeys is false, the user must click the buttons of the up-down control with the mouse. To set a companion control use the Associate property.

Note:	Up-down controls can respond to only the Up and Down arrow keys, even when the value of Orientation is udHorizontal.


TCustomUpDown::Associate

TCustomUpDown	See also

Specifies a companion control for the up-down control.

__property Controls::TWinControl* Associate = {read=FAssociate, write=SetAssociate};

Description

Use Associate to link the up-down control to a companion control (sometimes called a buddy window). The up-down control automatically positions itself on the outer edge of the companion control and adjusts its height to match the companion control.

At design-time the companion control does not move with the up-down control. To keep the up-down control and its companion control together at design time, either multi-select both controls before moving them, or first move the companion control and then reset the Associate property for the up-down control.


TCustomUpDown::Increment

TCustomUpDown	See also

Specifies the amount the Position value changes each time the up or down button is pressed.

__property int Increment = {read=FIncrement, write=SetIncrement, default=1};

Description

Use Increment to control the granularity of changes the up-down control can make. Set Increment to indicate the number of units between Min and Max the Position moves whenever the user clicks on one of the arrow buttons. Increment represents the mapping between the units used to specify Min, Max, and Position, and the logical units represented by the up-down control.


TCustomUpDown.Max

TCustomUpDown	See also

Specifies the maximum value of the Position property.

__property short Max = {read=FMax, write=SetMax, default=100};

Description

Use Max to provide an upper limit to the range of values the Position property can assume.


TCustomUpDown.Min

TCustomUpDown	See also

Specifies the minimum value of the Position property.

__property short Min = {read=FMin, write=SetMin, nodefault};

Description

Use Min to provide a lower limit to the range of values the Position property can assume.


TCustomUpDown::Orientation

TCustomUpDown	See also

Specifies the direction that the arrow keys point.

enum TUDOrientation { udHorizontal, udVertical };

__property TUDOrientation Orientation = {read=FOrientation, write=SetOrientation, default=1};

Description

Use Orientation to determine the orientation of the arrow buttons. These are the possible values:

Value	Meaning

udHorizontal	The arrow buttons point to the left and right, and appear side by side.

udVertical	The arrow buttons point up and down and are stacked vertically.

Note:	Even when the Orientation is udHorizontal, the up-down control can respond only to the Up and Down arrow keys.


TCustomUpDown::Position

TCustomUpDown	See also

Specifies the current value represented by the up-down control.

__property short Position = {read=GetPosition, write=SetPosition, nodefault};

Description

Use Position to get or change the value the up-down control represents. Position must be a value between Min and Max.

When the Associate property specifies an edit control, its text is automatically set to the value of Position. When Position changes, the text of the edit control is updated. If the Associate property is NULL, use the OnClick event to respond to changes in the value of Position.


TCustomUpDown::Thousands

TCustomUpDown	See also

Determines whether a thousands separator appears between every three digits of a decimal string.

__property bool Thousands = {read=FThousands, write=SetThousands, default=1};

Description

Use Thousands to control the formatting of the text of the companion control of the up-down control. If Thousands is true, a separator appears between every three digits. The numeric value that is displayed by the companion control is given by the Position property.


TCustomUpDown::Wrap

TCustomUpDown 	See also

Specifies how the up-down control handles attempts to exceed the value of Max or Min.

__property bool Wrap = {read=FWrap, write=SetWrap, nodefault};

Description

Use Wrap to specify whether the up-down control treats the range determined by the Max and Min properties as a continuous loop. If Wrap is true, the value of Position becomes the value of the Min property when the user increments Position beyond the value of Max, and becomes the value of Max when the user decrements Position beyond the value of Min.


TCustomUpDown events

TCustomUpDown	Alphabetically	Legend

In TCustomUpDown

OnChanging

OnClick


TCustomUpDown events

TCustomUpDown	By object	Legend

OnChanging

OnClick


TCustomUpDown::OnChanging

TCustomUpDown	See also

Occurs when the position of an up-down control is about to change.

typedef void __fastcall (__closure *TUDChangingEvent)(System::TObject* Sender, bool &AllowChange);

__property TUDChangingEvent OnChanging = {read=FOnChanging, write=FOnChanging};

Description

Write an OnChanging event handler to conditionally disallow changes to the value of Position. Set the AllowChange parameter to false to prevent a change to the current value of Position.

OnChanging occurs both when the user clicks the arrow buttons of the up-down control and when an attempt is made to change the value of Position programmatically. To determine which button the user clicked, use the OnClick event, which precedes the OnChanging event.


TCustomUpDown::OnClick

TCustomUpDown	See also 	Example

Occurs when the user clicks an arrow button.

enum TUDBtnType { btNext, btPrev };

typedef void __fastcall (__closure *TUDClickEvent)(System::TObject* Sender, TUDBtnType Button);

__property TUDClickEvent OnClick = {read=FOnClick, write=FOnClick}

Description

Write an OnClick event handler to take specific action when the user clicks one of the arrow buttons. For example, use an OnClick event handler to track the direction in which Position is about to change so that an OnChanging event handler, which is called immediately afterward, can determine whether the change should be allowed. If the Associate property is not used to automatically update the text of an edit control when the value of Position changes, use the OnClick event handler to respond to changes just before the value of Position is changed.

The Button parameter specifies how the value of Position is about to change. When Button is btNext, the Up or Right arrow was clicked, and the value of Position is about to increase by Increment. When Button is btPrev, the Down or Left arrow was clicked, and the value of Position is about to decrease by Increment.


TCustomUpDown methods

TCustomUpDown	Alphabetically	Legend

In TCustomUpDown

~TCustomUpDown

CanChange

Click

CreateParams

CreateWnd

Notification

TCustomUpDown

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomUpDown methods

TCustomUpDown	By object	Legend

~TCustomUpDown

Assign

BeginDrag

BringToFront

Broadcast

CanChange

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

ContainsControl

ControlAtPos

CreateParams

CreateWnd

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Notification

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TCustomUpDown

Update

UpdateControlState


TCustomUpDown::CanChange

TCustomUpDown	See also

Indicates whether the value of Position can be changed.

bool __fastcall CanChange(void);

Description

CanChange is called automatically when the user clicks the arrow buttons or the an attempt is made to change the value of Position programmatically. CanChange generates an OnChanging event, and allows the change unless it is prevented by an OnChanging event handler.

Override CanChange to prevent changes to the value of Position that are not limited by an OnChanging event handler, or to block the OnChanging event.


TCustomUpDown::Click

TCustomUpDown	See also

Generates an OnClick event.

enum TUDBtnType { btNext, btPrev };

HIDESBASEDYNAMIC void __fastcall Click(TUDBtnType Button);

Description

Click is called automatically when the user clicks an arrow button or presses an Up or Down arrow key. Override this method to specify special processing that should occur before the OnClick event handler executes, or to block the OnClick event. The Button parameter specifies which button was clicked: btNext refers to the Up or Right arrow, and btPrev refers to the Down or Left arrow.


TCustomUpDown::TCustomUpDown

TCustomUpDown	See also

Creates and initializes an instance of TCustomUpDown.

__fastcall virtual TCustomUpDown(Classes::TComponent* AOwner);

__fastcall TCustomUpDown(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not create instances of TCustomUpDown. TCustomUpDown is intended only as a base class. Instead, create TCustomUpDown descendants such as TUpDown.

The first contructor syntax takes a single Component as a parameter that provides the updown control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. The second syntax takes a window handle as a parameter and embeds the updown control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object’s constructor, TCustomUpDown initializes the following properties:

•	Height and Width are given values based on the size of scroll bar arrows.

•	ArrowKeys is set to true.

•	Max is set to 100 and Increment is set to 1.

•	AlignButton is set to udRight and Orientation is set to udVertical.

•	Thousands is set to true.


TCustomUpDown::TCustomUpDown
TCustomUpDown::CreateParams

TCustomUpDown	See also

Initializes the window creation parameters for the up-down control.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams is called automatically before the window for an up-down control is created. CreateParams calls the parent class’s method, then sets the Params parameter to reflect the values of the AlignButton, ArrowKeys, Orientation, Thousands, and Wrap properties.


TCustomUpDown::TCustomUpDown
TCustomUpDown::CreateWnd

TCustomUpDown	See also

Creates the window used by the up-down control.

virtual void __fastcall CreateWnd(void);

Description

After calling the parent class’s method to create the up-down control’s window, CreateWnd sends the newly created windows messages so that it reflects the current values of the Associate, Increment, Max, Min, and Position properties.


TCustomUpDown::Notification

TCustomUpDown	See also

Responds to notifications when components are about to be created or destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the parent class’s method, Notification checks whether the control specified by the Associate property is about to be destroyed, and if so, sets the Associate property to NULL.


TCustomUpDown::~TCustomUpDown

TCustomUpDown

~TCustomUpDown frees the memory associated with the TCustomUpDown object.

__fastcall virtual ~TCustomUpDown(void) { }

Description

Do not call ~TCustomUpDown directly. Instead, use the delete keyword on the object, which causes ~TCustomUpDown to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TCustomWinSocket

Hierarchy	Properties	Methods	Events	See also

TCustomWinSocket is the base class for all Windows socket objects.

Unit

scktcomp

Description

TCustomWinSocket introduces properties, events, and methods to describe an endpoint in a Windows socket connection. Descendants of TCustomWinSocket are used by socket components to manage the Windows socket API calls and to store information about a socket communication link.

A Windows socket encapsulates a set of communication protocols to allow the application to connect to other machines for reading or writing information. Windows sockets provide connections based on the TCP/IP protocol. They also allow connections that use the Xerox Network System (XNS), Digital’s DECnet protocol, or Novell’s IPX/SPX family. Sockets allow an application to form connections to other machines without being concerned with the details of the actual networking software.

Descendants of TCustomWinSocket represent different endpoints in socket connections. TClientWinSocket represents the client endpoint of a socket communication link to a server socket. TServerWinSocket represents the server endpoint of a listening connection. TServerClientWinSocket represents the server endpoint of a socket communication link to a client socket.


TCustomWinSocket properties

TCustomWinSocket	Alphabetically	Legend

In TCustomWinSocket

Addr

ASyncStyles

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle


TCustomWinSocket properties

TCustomWinSocket	By object	Legend

Addr

ASyncStyles

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle


TCustomWinSocket::Addr

TCustomWinSocket	See also

Specifies the internet socket address structure used in Windows socket API calls to represent the full specification of the local socket port.

in_addr __fastcall LookupName(const System::AnsiString name);

type

Description

Use Addr to represent the port used by the socket on the local system when working directly with Windows socket API calls. The value of Addr is determined by the values of the LocalAddress and LocalPort properties.


TCustomWinSocket::ASyncStyles

TCustomWinSocket	See also

Determines which asynchronous events the socket can receive.

__property TAsyncStyles ASyncStyles = {read=FAsyncStyles, write=SetAsyncStyles, nodefault};

Description

Use ASyncStyles to determine what sorts of notifications the socket needs to respond to. Set ASyncStyles to change the notifications that the socket receives from the socket connection. ASyncStyles is a set drawn from the following values

Value	Meaning

asRead	The socket receives notification that the connection is ready for reading.

asWrite	The socket receives notification that the connection is ready for writing.

asOOB	The socket receives notification when out-of-band data arrives.

asAccept	The socket receives notification when another socket requests a connection.

asConnect	The socket receives notification when a communication link to another socket is opened.

asClose	The socket receives notification when a communication link to another socket is terminated.

Any notification specified by ASyncStyles arrives as a window message to the Handle property.

Note:	If the socket is a non-blocking socket, then ASyncStyles should include asRead and asWrite so that the socket will be informed of asynchronous reading and writing events.


TCustomWinSocket::Connected

TCustomWinSocket	See also

Indicates whether the socket connection is open and available for communication with other machines.

__property bool Connected = {read=FConnected, nodefault};

Description

Read Connected before trying to use or change the Windows socket connection. Connected indicates whether the socket connection has been established. When Connected is true, the Windows socket is open and available for use. When Connected is false, the Windows socket is closed and can be changed.

To open a client Windows socket, use the Open method. To open a server Windows socket, use the Listen method. The Windows socket that represents the server endpoint of a connection to a client socket is opened in its constructor.

To close a Windows socket, use the Close method.


TCustomWinSocket::Data

TCustomWinSocket

Points to application-specific data associated with the socket.

__property void * Data = {read=FData, write=FData};

Description

Use Data to associate information specific to the socket connection with the Windows socket object. For example, Data can be used to store access and authentication information used by a server socket to evaluate client connection requests.

Data can store information in a thread-safe manner that would otherwise require the use of global variables. This is useful given the multi-threaded nature of many client-server applications.


TCustomWinSocket::Handle

TCustomWinSocket	See also

Specifies the handle of the window that receives notifications from the Windows socket.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Use Handle to send messages to the Windows socket or to subclass the Window procedure that receives messages of asynchronous events from the socket connection.


TCustomWinSocket::LocalAddress

TCustomWinSocket	See also

Specifies the IP address of the local system that was bound to the socket connection.

__property System::AnsiString LocalAddress = {read=GetLocalAddress};

Description

LocalAddress is a string of four numeric (byte) values in the standard internet dot notation, such as

Each address identifies the system and indicates the types of interfaces supported by the socket. A single system (machine) can support multiple addresses. LocalAddress is the address from among the possible addresses supported by the local system that is bound to the socket connection.

A single LocalAddress can be used simultaneously by multiple socket connections. Each of those connections must have a unique LocalPort number to distinguish it from other connections to the same LocalAddress.


TCustomWinSocket::LocalHost

TCustomWinSocket	See also

Specifies the name of the local system.

__property System::AnsiString LocalHost = {read=GetLocalHost};

Description

Use LocalHost to get the name of the system that is running the application which uses the Windows socket. LocalHost is a string containing the domain name and service of the local socket endpoint, such as

LocalHost provides an alias for the local IP address given in the LocalAddress property. Most Intranets provide host names for the IP addresses of systems on the net. On Windows 95 and NT machines, if a host name is not available, create one for the local IP address by entering the name into the HOSTS file. See the Microsoft documentation on Windows sockets for more information on the HOSTS file.


TCustomWinSocket::LocalPort

TCustomWinSocket	See also

Specifies the ID number of the port used by the socket connection.

__property int LocalPort = {read=GetLocalPort, nodefault};

Description

Use LocalPort to determine the port number that is bound to the socket connection. For server endpoints of listening connections, LocalPort is the ID associated with the service the server socket provides. For client or server endpoints of connections to another socket, LocalPort is usually an arbitrary value picked when the connection was made.

Port numbers allow a single system, identified by the LocalAddress property, to host multiple connections simultaneously. Each combination of LocalPort and LocalAddress can only be bound to a single socket connection. This combination is represented by the Addr property.

Many values of LocalPort are associated by convention with a particular service such as ftp or http. To determine whether the value of LocalPort is associated with a specific service, use the LookupService method.


TCustomWinSocket::RemoteAddr

TCustomWinSocket	See also

Specifies the internet socket address structure used in Windows socket API calls to represent the full specification of the remote socket port.

__property sockaddr_in RemoteAddr = {read=GetRemoteAddr};

Description

When working directly with Windows socket API calls, use RemoteAddr to represent the port used by the socket on the other end of the connection. The value of RemoteAddr is determined by the values of the RemoteAddress and RemotePort properties.


TCustomWinSocket::RemoteAddress

TCustomWinSocket	See also

Specifies the IP address of the remote system that was bound to the socket connection.

__property System::AnsiString RemoteAddress = {read=GetRemoteAddress};

Description

RemoteAddress is a string of four numeric (byte) values in the standard internet dot notation, such as

Each address identifies the system on the other end of the socket connection and indicates the types of interfaces supported by the remote socket. A single system can support multiple addresses. RemoteAddress is the address from among the possible addresses supported by the remote system that is bound to the socket connection.

A single RemoteAddress may be participating in multiple socket connections. Each of those connections has a unique RemotePort number to distinguish it from other connections to the same RemoteAddress. The RemoteAddr property uniquely identifies the RemoteAddress and RemotePort combination used by the socket connection.


TCustomWinSocket::RemoteHost

TCustomWinSocket	See also

Specifies the name of the remote system.

__property System::AnsiString RemoteHost = {read=GetRemoteHost};

Description

Use RemoteHost to get the name of the system on the other end of the socket connection. RemoteHost is a string containing the domain name and service of the remote endpoint of the socket connection, such as

LocalHost provides an alias for the local IP address given in the RemoteAddress property.


TCustomWinSocket::RemotePort

TCustomWinSocket	See also

Specifies the ID number of the port used by the RemoteHost to form the socket connection.

__property int RemotePort = {read=GetRemotePort, nodefault};

Description

Use RemotePort to determine the port number used by the socket on the other end of the socket connection.

Port numbers allow a single system, identified by the RemoteAddress or RemoteHost property, to host multiple connections simultaneously. Each combination of RemotePort and RemoteAddress can only be bound to a single socket connection. This combination is represented by the RemoteAddr property.

Many port numbers are associated by convention with a particular service such as ftp or http. To determine whether the value of RemotePort is associated with a specific service, use the LookupService method.

Note:	If a client socket requests a specific port to indicate a desired service, the value of RemotePort for the actual connection may differ from the requested port number. Most server sockets listen on the port associated with a service, but switch to an arbitrary available port number for forming connections.


TCustomWinSocket::SocketHandle

TCustomWinSocket	See also

Specifies the Windows handle for the socket.

__property int SocketHandle = {read=FSocket, nodefault};

Description

Use SocketHandle for Windows socket API calls that require the handle to the socket. When the Connected property is false, SocketHandle is INVALID_SOCKET.

SocketHandle is set to a valid Windows socket handle by the Listen or Open method.


TCustomWinSocket events

TCustomWinSocket	Alphabetically

In TCustomWinSocket

OnErrorEvent

OnSocketEvent


TCustomWinSocket events

TCustomWinSocket	By object

OnErrorEvent

OnSocketEvent


TCustomWinSocket::OnErrorEvent

TCustomWinSocket	See also

Occurs when the socket fails in making, using, or shutting down a connection.

__property TSocketErrorEvent OnErrorEvent = {read=FOnErrorEvent, write=FOnErrorEvent};

Description

Socket components provide an OnErrorEvent event handler that converts error notifications into error events on the socket component. Most applications will therefor not provide an event handler for OnErrorEvent.

The Sender parameter is the Windows socket object that owns the event handler. Usually, this is the same as the Socket parameter.

The Socket parameter indicates the Windows socket object which encounters the error condition.

The ErrorEvent parameter indicates what the socket was trying to do when the error occurred. It has one of the following values:

Value	Meaning

eeGeneral	The socket received an error message that does not fit into any of the following categories.

eeSend	An error occurred when trying to write to the socket connection.

eeReceive	An error occurred when trying to read from the socket connection.

eeConnect	For client sockets, this indicates that the client socket can’t locate the server, or that a problem on the server prevents the opening of a connection. For server sockets, this indicates that a client connection request that has already been accepted could not be completed.

eeDisconnect	An error occurred when trying to close a connection.

eeAccept	For server sockets only, this indicates that a problem occurred when trying to accept a client connection request.

The ErrorCode parameter is the error code received by the Windows socket object. Setting this value to 0 in the OnErrorEvent event handler prevents the socket from raising an exception. For information on possible error codes, see the Microsoft documentation on Windows sockets.


TCustomWinSocket::OnSocketEvent

TCustomWinSocket	See also

Occurs when the Windows socket receives notification of asynchronous events.

__property TSocketEventEvent OnSocketEvent = {read=FOnSocketEvent, write=FOnSocketEvent};

Description

Socket components provide an OnSocketEvent event handler that converts Windows socket notifications into events on the socket component. Most applications will therefor not provide an event handler for OnSocketEvent. Replacing this event handler can prevent some expected events from occurring.

The Sender parameter is the Windows socket object that owns the event handler. Usually, this is the same as the Socket parameter.

The Socket parameter indicates the Windows socket that generates or recieves notification of the event.

The SocketEvent parameter indicates the event that occured. It has one of the following values:

Value	Meaning

seLookup	(client sockets only) The Windows socket object is about to locate the server socket. Changing the propreties of the client socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will affect the attempted connection.

seConnecting	(client sockets only) The server socket has been located but the connection isn’t completed. This is the first opportunity to obtain the actual server port and IP address used for the connection, which may differ from those of the listening socket contacted initially.

seConnect	The socket connection has just been established. This is the point when a socket starts reading or writing over the connection.

seListen	(server sockets only) The Windows socket object has been initialized and is about to open a listening connection. Changing the propreties of the server socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will the listening connection.

seAccept	(server sockets only) A client connection request has just been accepted. This is the first opportunity to obtain the port and IP address of the individual client connection.

seWrite	The socket is ready for information to be written.

seRead	The socket is receiving information from a socket on the other end of the connection.


TCustomWinSocket methods

TCustomWinSocket	Alphabetically	Legend

In TCustomWinSocket

~TCustomWinSocket

Accept

Close

Connect

Disconnect

Error

Event

InitSocket

Listen

Lock

LookupName

LookupService

Open

Read

ReceiveBuf

ReceiveLength

ReceiveText

SendBuf

SendStream

SendStreamThenDrop

SendText

SetAsyncStyles

TCustomWinSocket

Unlock

Write

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TCustomWinSocket methods

TCustomWinSocket	By object	Legend

~TCustomWinSocket

Accept

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

Connect

DefaultHandler

Disconnect

Dispatch

Error

Event

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InitSocket

InstanceSize

Listen

Lock

LookupName

LookupService

MethodAddress

MethodName

NewInstance

Open

Read

ReceiveBuf

ReceiveLength

ReceiveText

SafeCallException

SendBuf

SendStream

SendStreamThenDrop

SendText

SetAsyncStyles

TCustomWinSocket

Unlock

Write


TCustomWinSocket::Accept

TCustomWinSocket	See also

Provides the interface for a method that accepts a connection to a client socket.

virtual void __fastcall Accept(int Socket);

Description

Accept is called automatically in response to notifications that a client socket is requesting a connection. The Socket parameter is the Windows socket handle for the socket that receives the notification.

The Accept method for TCustomWinSocket does nothing with the notification. Descendants of TCustomWinSocket that represent listening server sockets override this method to accept the connection to the client socket.

Accept is only called if the ASyncStyles property includes asAccept.


TCustomWinSocket::Close

TCustomWinSocket	See also

Shuts down the socket connection if it is open.

void __fastcall Close(void);

Description

Call Close to terminate an open socket connection. Close triggers an OnSocketEvent of type seDisconnect before the connection is shut down. If the Windows socket is a listening server socket, Close shuts down all open connections to client sockets before shutting down the listening connection.


TCustomWinSocket::Connect

TCustomWinSocket	See also

Provides the interface for a method that responds to connection notifications from client sockets.

virtual void __fastcall Connect(int Socket);

Description

Connect is called automatically in response to notifications that the client socket has successfully completed a connection to a server socket. The Socket parameter is the Windows socket handle for the socket that receives the notification.

The Connect method for TCustomWinSocket does nothing with the notification. Descendants of TCustomWinSocket that represent client sockets override this method to respond to connection notifications.

Connect is only called if the ASyncStyles property includes asConnect.


TCustomWinSocket::TCustomWinSocket

TCustomWinSocket	See also

Creates an instance of TCustomWinSocket from a Windows socket handle.

__fastcall TCustomWinSocket(int ASocket);

Description

Call TCustomWinSocket to create a Windows socket object. Most Windows socket objects are created automatically by the socket component that uses them. Applications may create their own Windows socket objects in an OnGetSocket event handler for a server socket component.

After calling the parent object’s constructor, TCustomWinSocket

•	Makes sure that Winsock.dll is initialized.

•	Allocates helper objects to manage multithreading issues.

•	Initializes ASyncStyles to [asRead, asWrite, asConnect, asClose]

•	Initializes the SocketHandle property to the ASocket parameter and sets the Connected property to reflect whether ASocket is the handle of a valid open Windows socket.

•	Initializes the Addr property.


TCustomWinSocket::~TCustomWinSocket

TCustomWinSocket	See also

Destroys an instance of TCustomWinSocket.

__fastcall virtual ~TCustomWinSocket(void);

Description

Do not call ~TCustomWinSocket directly in an application. Instead, use the delete keyword on the object, which causes ~TCustomWinSocket to be invoked automatically. Unless the Windows socket object is not used by a socket component, it is freed automatically by the socket component.

Most applications do not need to explicitly free Windows socket objects.  They are freed by the socket components that use them.


TCustomWinSocket::Disconnect

TCustomWinSocket	See also

Shuts down the socket connection represented by a Windows socket handle.

virtual void __fastcall Disconnect(int Socket);

Description

Disconnect is called by the Close method to terminate an individual socket connection.

Disconnect calls the Lock method to make sure the method is thread-safe. Then, it generates an OnSocketEvent of type seDisconnect. After the OnSocketEvent, Disconnect closes the connection. Finally, it calls Unlock to end the critical section started by Lock.


TCustomWinSocket::Error

TCustomWinSocket	See also

Generates an OnErrorEvent event.

DYNAMIC void __fastcall Error(TCustomWinSocket* Socket, TErrorEvent ErrorEvent, int &ErrorCode);

Description

Error is called automatically when the Windows socket object recieves error notifications. It generates the OnErrorEvent event. When overriding this method, be sure to call the inherited method, because socket components rely on the OnErrorEvent event for their own error handling.

The Socket parameter indicates the Windows socket object which encounters the error condition.

The ErrorEvent parameter indicates what the socket was trying to do when the error occurred. It has one of the following values:

Value	Meaning

eeGeneral	The socket received an error message that does not fit into any of the following categories.

eeSend	An error occurred when trying to write to the socket connection.

eeReceive	An error occurred when trying to read from the socket connection.

eeConnect	For client sockets, this indicates that the client socket can’t locate the server, or that a problem on the server prevents the opening of a connection. For server sockets, this indicates that a client connection request that has already been accepted could not be completed.

eeDisconnect	An error occurred when trying to close a connection.

eeAccept	For server sockets only, this indicates that a problem occurred when trying to accept a client connection request.

The ErrorCode parameter is the error code received by the Windows socket object. Changing this value to 0 in the Error method prevents the socket from raising an exception. For information on possible error codes, see the Microsoft documentation on Windows sockets.


TCustomWinSocket::Event

TCustomWinSocket	See also

Generates an OnSocketEvent event.

DYNAMIC void __fastcall Event(TCustomWinSocket* Socket, TSocketEvent SocketEvent);

Description

Error is called automatically when the Windows socket object recieves notifications or when it performs certain actions. It generates the OnSocketEvent event. When overriding this method, be sure to call the inherited method, because socket components rely on the OnSocketEvent event to generate many of their own events.

The Socket parameter indicates the Windows socket that generates or recieves notification of the event.

The SocketEvent parameter indicates the event that occured. It has one of the following values:

Value	Meaning

seLookup	(client sockets only) The Windows socket object is about to locate the server socket. Changing the propreties of the client socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will affect the attempted connection.

seConnecting	(client sockets only) The server socket has been located but the connection isn’t completed. This is the first opportunity to obtain the actual server port and IP address used for the connection, which may differ from those of the listening socket contacted initially.

seConnect	The socket connection has just been established. This is the point when a socket starts reading or writing over the connection.

seListen	(server sockets only) The Windows socket object has been initialized and is about to open a listening connection. Changing the propreties of the server socket has no effect at this point, but changes to the Windows socket object specified by the Socket parameter will the listening connection.

seAccept	(server sockets only) A client connection request has just been accepted. This is the first opportunity to obtain the port and IP address of the individual client connection.

seWrite	The socket is ready for information to be written.

seRead	The socket is receiving information from a socket on the other end of the connection.


TCustomWinSocket::InitSocket

TCustomWinSocket	See also

Generates a windows internet socket address structure from a description of the desired socket port.

sockaddr_in __fastcall InitSocket(const System::AnsiString Name, const System::AnsiString Address, const System::AnsiString Service, Word Port, bool Client);

Description

Applications can not call InitSocket. It is called by the Open or Listen method to obtain a Windows internet socket address structure for the parameters obtained from a socket component. InitSocket is exposed as a protected method so that component writers can perform additional initializations before a socket connection is opened.

The Name parameter is the host name for the socket.The Address parameter is the IP address. The Service parameter is the service for which the socket is to used. The Port parameter is the port number for the socket. The Client parameter indicates whether the socket address structure is to be used by a client socket to describe the destination of a connection or by a server socket to describe the listening connection.

The TInAddr portion of the Windows internet socket address is obtained from the host name if it is given. Otherwise the Address parameter is used. If Client is true, either the Name or the Address parameter must be specified. If Client is false, they may both be left blank to specify a server that listens on multiple addresses.

If port number for the Windows internet socket address is obtained from the Service parameter if it is given. Otherwise, the Port parameter is used. One of these two parameters must be specified.


TCustomWinSocket::Listen

TCustomWinSocket	See also

Opens a listening connection for a server socket.

void __fastcall Listen(const System::AnsiString Name, const System::AnsiString Address, const System::AnsiString Service, Word Port, int QueueSize);

Description

Server socket components call Listen to open a listening connection.

Listen creates the windows socket that will make the listening connection, and binds the Windows internet socket address derived from the parameters to the socket. Listen then generates an OnSocketEvent of type seListen. Finally, Listen opens the socket as a listening connection with a queue that can hold QueueSize client requests, setting the Connected property to true.

The Name, Address, Service, and Port parameters are taken from the Host, Address, Service and Port properties of the server socket component. The QueueSize is set to 5 by TServerSocket.


TCustomWinSocket::Lock

TCustomWinSocket	See also

Starts a critical section, blocking all other execution threads until the Unlock method is called.

void __fastcall Lock(void);

Description

Call Lock before beginning a section of code that is not thread-safe. Call Unlock when the critical section of code is completed. Unless absolutely necessary, do not use Lock to lock lengthy operations such as reading and writing over a blocking connection. Locking lengthy operations can severely impact performance, because all execution threads in the application that use the Windows socket object must wait until Unlock is called.


TCustomWinSocket::LookupName

TCustomWinSocket	See also

Generates the TInAddr portion of a Windows internet socket address structure from a host name.

in_addr __fastcall LookupName(const System::AnsiString name);

Description

Call LookupName to obtain the internet address associated with the system identified by the name parameter. LookupName is used by InitSocket to generate the TInAddr portion of the Windows internet socket address structure.


TCustomWinSocket::LookupService

TCustomWinSocket	See also

Returns the port number associated with a specific service.

int __fastcall LookupService(const System::AnsiString service);

Description

Call LookupService to obtain the standard port number for the service named by the service parameter. Windows provides a number of standard service names such as ftp, http, finger, or time. Each standard service is associated, by convention, with a specific port number. These standard port numbers allow client sockets to indicate the desired service by requesting a specific port number. They allow server sockets to listen on an expected port number for the service offered. Servers can specify additional services and their associated ports in a SERVICES file. For more information on the SERVICES file, see the Microsoft documentation for Windows sockets.

InitSocket calls LookupService to obtain the port number for the Service specified by a socket component.


TCustomWinSocket::Open

TCustomWinSocket	See also

Opens a connection to a remote socket.

void __fastcall Open(const System::AnsiString Name, const System::AnsiString Address, const System::AnsiString Service, Word Port);

Description

Client socket components call Open to open a connection to a server socket.

Open creates the windows socket that will connect to the server socket, and generates an OnSocketEvent of type seLookup. After the OnSocketEvent, Open binds the Windows internet socket address derived from the parameters to the socket, locating the server socket. Open then generates an OnSocketEvent of type seConnecting. When the connection is accepted by the server socket, Open completes the connection to the server socket. Then it generates an OnSocketEvent of type seConnect. After the OnSocketEvent, the Connected property is set to true.

The Name, Address, Service, and Port parameters are taken from the Host, Address, Service and Port properties of the client socket component.


TCustomWinSocket::Read

TCustomWinSocket	See also

Generates an OnSocketEvent of type seRead in response to notifications that the socket connection is ready.

virtual void __fastcall Read(int Socket);

Description

Read is called in response to asynchronous notifications that the socket connection is ready for reading. The Windows socket can then read from the connection in the OnSocketEvent event handler or the socket component can read from the connection in an OnRead or OnClientRead event handler. The event handler can use the ReceiveBuf method or the ReceiveText method to read the information from the connection.

Note:	Read is only called for asynchronous read notifications in a non-blocking socket. Blocking sockets must use a TWinSocketStream object for reading. The TWinSocketStream object waits for the remote socket to be ready before transferring information.


TCustomWinSocket::ReceiveBuf

TCustomWinSocket	See also

Reads up to Count bytes from the socket connection into the Buf parameter.

int __fastcall ReceiveBuf(void *Buf, int Count);

Description

Use ReceiveBuf to read from the socket connection in the OnSocketEvent event handler of a Windows socket object or in the OnRead or OnClientRead event handler of a socket component. ReceiveBuf returns the number of bytes actually read.

ReceiveBuf only works in response to a read notification to a non-blocking windows socket. Blocking sockets must use a TWinSocketStream for reading. The TWinSocketStream object waits for the remote socket to be ready before transferring information.

Note:	While the ReceiveLength method can return an estimate of the size of buffer required to retrieve information from the socket, the number of bytes it returns is not necessarily accurate.


TCustomWinSocket::ReceiveLength

TCustomWinSocket	See also

Returns the number of bytes ready to be sent over the socket connection.

int __fastcall ReceiveLength(void);

Description

Call ReceiveLength to determine the amount of information to read over the socket connection in response to an asynchronous read notification.

Note:	ReceiveLength is not guarenteed to be accurate for streaming socket connections.


TCustomWinSocket::ReceiveText

TCustomWinSocket	See also

Reads a string from the socket connection.

System::AnsiString __fastcall ReceiveText();

Description

Use ReceiveText to read a string from the socket connection in the OnSocketEvent event handler of a Windows socket object or in the OnRead or OnClientRead event handler of a socket component. ReceiveText returns the number of bytes in the string.

ReceiveText only works in response to a read notification to a non-blocking windows socket. Blocking sockets must use a TWinSocketStream for reading. The TWinSocketStream object waits for the remote socket to be ready before transferring information.


TCustomWinSocket::SendBuf

TCustomWinSocket	See also

Writes Count bytes to the socket connection from the Buf parameter.

int __fastcall SendBuf(void *Buf, int Count);

Description

Use SendBuf to write to the socket connection. The writing may occur in the OnSocketEvent event handler of a Windows socket object or in the OnWrite or OnClientWrite event handler of a socket component. Alternately, SendBuf may write from a socket that is expected to write to the connection without a notification to signal the connection’s readiness to read. SendBuf returns the number of bytes actually written. If an error occurs while writing to the connection, SendBuf terminates the connection and raises an ESocketError exception.


TCustomWinSocket::SendStream

TCustomWinSocket	See also

Writes all the information that can be read from the AStream parameter to the socket connection.

bool __fastcall SendStream(Classes::TStream* AStream);

Description

Use SendStream to write to the socket connection. The writing may occur in the OnSocketEvent event handler of a Windows socket object or in the OnWrite or OnClientWrite event handler of a socket component. Alternately, SendStream may write from a socket that is expected to write to the connection without a notification to signal the connection’s readiness to read. SendStream reads information from the stream indicated by AStream and writes it to the socket connection. The value returned by SendStream indicates whether any information was successfully written to the connection.

Note:	The Stream passed as a parameter to SendStream becomes “owned” by the windows socket object.  The Windows socket object frees the stream when it is finished with it.  Do not attempt to free the stream after it has been passed as a parameter.


TCustomWinSocket::SendStreamThenDrop

TCustomWinSocket	See also

Writes all the information that can be read from the AStream parameter to the socket connection and then terminates the connection.

bool __fastcall SendStreamThenDrop(Classes::TStream* AStream);

Description

Use SendStreamThenDrop to write to a socket connection when the connection is no longer needed after the writing is complete. SendStream reads information from the stream indicated by AStream and writes it to the socket connection, shutting down the connection when it is done. The value returned by SendStream indicates whether any information was successfully written to the connection.

Note:	The Stream passed as a parameter to SendStream becomes “owned” by the windows socket object.  The Windows socket object frees the stream when it is finished with it.  Do not attempt to free the stream after it has been passed as a parameter.


TCustomWinSocket::SendText

TCustomWinSocket	See also

Writes the string S to the socket connection.

void __fastcall SendText(const System::AnsiString S);

Description

Use SendText to write a string to the socket connection. The writing may occur in the OnSocketEvent event handler of a Windows socket object or in the OnWrite or OnClientWrite event handler of a socket component. Alternately, SendText may write from a socket that is expected to write to the connection without a notification to signal the connection’s readiness to read. If an error occurs while writing to the connection, SendText terminates the connection and raises an ESocketError exception.


TCustomWinSocket::SetAsyncStyles

TCustomWinSocket	See also

Sets the AsyncStyles property.

void __fastcall SetAsyncStyles(TAsyncStyles Value);

Description

SetAsyncStyles implements the AsyncStyles property. Override SetAsyncStyles to limit the value of AsyncStyles to notifications that are appropriate to a particular type of Windows socket.


TCustomWinSocket::Unlock

TCustomWinSocket	See also

Reenables execution in other threads after a critical section begun by the Lock method.

void __fastcall Unlock(void);

Description

Call Unlock at the end of a section of code that is not thread-safe. Every call to Unlock should match a call to the Lock method at the beginning of the critical section of code.


TCustomWinSocket::Write

TCustomWinSocket	See also

Generates an OnSocketEvent of type seWrite in response to notifications that the socket connection is ready.

virtual void __fastcall Write(int Socket);

Description

Write is called in response to asynchronous notifications that the socket connection is ready for the socket to send information. The Windows socket can then write to the connection in the OnSocketEvent event handler or the socket component can write to the connection in an OnWrite or OnClientWrite event handler. The event handler can use the SendBuf method, the SendStream method, or the SendText method to write the information to the connection.

Note:	Write is only called for asynchronous write notifications in a non-blocking socket. Blocking sockets must use their own mechanisms for determining when the connection is ready for the socket to write.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject


 TDatabase

Hierarchy	Properties	Methods	Events	See also

TDatabase provides discrete control over a connection to a single database in a database application.

Unit

dbtables

Description

Use TDatabase when a database application requires any of the following control over a database connection:

•	Persistent database connections

•	Customized database server logins

•	Transaction control

•	Application-specific BDE aliases

TDatabase is especially important for the control it permits over database transaction processing with the BDE when connected to a remote SQL database server.

Note:	Explicit declaration of a TDatabase component for each database connection in an application is optional if the application does not need to explicitly control that connection. If a TDatabase component is not explicitly declared and instantiated for a database connection, a temporary database component with a default set of properties is created for it at runtime.


TDatabase properties

TDatabase	Alphabetically	Legend

In TDatabase

AliasName

Connected

DatabaseName

DataSetCount

DataSets

Directory

DriverName

Handle

HandleShared

InTransaction

IsSQLBased

KeepConnection

Locale

LoginPrompt

Params

Session

SessionAlias

SessionName

Temporary

TraceFlags

TransIsolation

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDatabase properties

TDatabase	By object	Legend

AliasName

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Connected

DatabaseName

DataSetCount

DataSets

DesignInfo

Directory

DriverName

Handle

HandleShared

InTransaction

IsSQLBased

KeepConnection

Locale

LoginPrompt

Name

Owner

Params

Session

SessionAlias

SessionName

Tag

Temporary

TraceFlags

TransIsolation

VCLComObject


TDatabase::AliasName

TDatabase	See also	Example

Specifies the Borland Database Engine (BDE) alias used by this database connection.

__property System::AnsiString AliasName = {read=GetAliasName, write=SetAliasName};

Description

Use AliasName to specify the name of an existing BDE alias for the database component. A BDE alias contains database configuration information for connection to a specific kind of database, such as InterBase, dBASE, or Paradox. The configuration information associated with a BDE alias differs by database type.

If an application sets AliasName, any value previously assigned to the DriverName property is cleared because the alias automatically specifies a driver name as one of its parameters. Other alias connection information is stored in the Params property when AliasName is set.

Note:	Attempting to set AliasName when the Connected property is true raises an exception.

Note:	An application can specify the DatabaseName, DriverName, and Params properties rather than setting AliasName if the desired BDE alias configuration does not already exist. An application can also provide an application-specific “alias” name by setting DatabaseName when AliasName is already set.

Tip:	At design time double-click a TDatabase component to invoke the Database editor and set the AliasName.


TDatabase::Connected

TDatabase	See also	Example

Indicates whether or not a database connection is active.

__property bool Connected = {read=GetConnected, write=SetConnected, default=0};

Description

Set Connected to true to establish a database connection without opening a dataset. Set Connected to false to close a database connection. An application can check Connected to determine the current status of a database connection. If Connected is true, the database connection is active; if false, and the KeepConnection property is also false, then the connection is inactive.

Note:	Set KeepConnection to true to avoid having to log in to the server each time a database connection is reopened.


TDatabase::DatabaseName

TDatabase	See also	Example

Specifies the name of the database to associate with this database component.

__property System::AnsiString DatabaseName = {read=FDatabaseName, write=SetDatabaseName};

Description

Use DatabaseName to specify the name of the database to use with a database component. If DatabaseName is the same as an existing Borland Database Engine (BDE) alias, then the AliasName and DriverName properties need not be set. If DatabaseName does not match an existing BDE alias, then either the application must also supply a valid alias in the AliasName property in addition to the DatabaseName, or it must supply the DriverName and Params properties.

DatabaseName can be a fully qualified path name when connecting to a Paradox or dBASE database.

Note:	Attempting to set DatabaseName when the Connected property is true raises an exception.

Tip:	At design time double-click a TDatabase component to invoke the Database editor and set the DatabaseName.


TDatabase::DataSetCount

TDatabase	See also 	Example

Indicates the number of active datasets associated with the database component.

__property int DataSetCount = {read=GetDataSetCount, nodefault};

Description

Use DataSetCount to determine the number of currently active datasets associated with the database component. As datasets are opened and closed this value changes appropriately.


TDatabase::DataSets

TDatabase	See also 	Example

Provides an indexed array of all active datasets for a database component.

__property TDBDataSet* DataSets[int Index] = {read=GetDataSet};

Description

Use DataSets to access active datasets associated with a database component. An active dataset is one that is currently open.


TDatabase::Directory

TDatabase	See also

Specifies the working directory for a Paradox or dBASE database.

__property System::AnsiString Directory = {read=GetDirectory, write=SetDirectory};

Description

Use Directory at runtime to change or retrieve the working directory for a Paradox or dBASE database. This is the location these databases use to create temporary tables at runtime.

Ordinarily a directory location is specified in the PATH parameter of the database alias (specified by the AliasName property). At runtime, however, some applications may need to change the working directory after a database is opened.

To change the value of Directory at runtime, a database must already be open, or an exception is raised. Clearing the current value of Directory sets its value to the original working directory specified when the database was first opened.

Note:	Do not use Directory when connected to remote databases. An exception is raised in these circumstances. An exception is also raised if an application accesses Directory when the database is closed.


TDatabase::DriverName

TDatabase	See also	Example

Specifies the name of the BDE driver for the database.

__property System::AnsiString DriverName = {read=GetDriverName, write=SetDriverName};

Description

Use DriverName to specify the name of the BDE driver to use for databases connections that do not specify an AliasName, but that do specify a DatabaseName. DriverName must be a valid BDE driver (for instance, STANDARD, ORACLE, SYBASE, or INTERBASE).

Note:	If an application sets DriverName, it must also specify connection parameters in the Params property. Ordinarily the alias specified in the AliasName property supplies connection parameters, but when DriverName is set, the AliasName property is automatically cleared to avoid BDE driver name contention.

Attempting to set DriverName when the Connected property is true raises an exception.

Tip:	At design time double-click a TDatabase component to invoke the Database editor and set the DriverName.


TDatabase::Handle

TDatabase	See also

Specifies the Borland Database Engine (BDE) database handle.

__property Bde::hDBIDb Handle = {read=FHandle, write=SetHandle};

Description

Use Handle only to bypass TDatabase methods and make direct calls to the directly to the BDE API. Many BDE function calls require a handle parameter. Handle is assigned an initial value when a database is opened.

Note:	Do not use this property unless an application requires BDE functionality not available through standard C++Builder components.


TDatabase::HandleShared

TDatabase	See also

Specifies whether or not to share a database handle.

__property bool HandleShared = {read=FHandleShared, write=FHandleShared, default=0};

Description

Use HandleShared to indicate that a database component can share its BDE handle in a session component. Set HandleShared to true to avoid namespace conflicts for database components that appear in a remote data module, or that appear in data modules you inherit from the Object Repository.


TDatabase::InTransaction

TDatabase	See also

Indicates whether a database transaction is in progress or not.

__property bool InTransaction = {read=GetInTransaction, nodefault};

Description

Examine InTransaction at run-time to determine if a database transaction is currently in progress. InTransaction is true if a transaction is in progress, false otherwise.

The value of InTransaction cannot be changed directly. Calling StartTransaction sets InTransaction to true. Calling Commit or Rollback sets InTransaction to false.


TDatabase::IsSQLBased

TDatabase	See also

Indicates if a database component is using either the Borland Database Engine (BDE) SQL Links driver or the BDE ODBC socket.

__property bool IsSQLBased = {read=FSQLBased, nodefault};

Description

Examine IsSQLBased at runtime to determine if a database connection is using a BDE SQL Links driver, the ODBC socket, or the Paradox, dBASE, and ASCII text file STANDARD driver. If IsSQLBased is true, the connection is using an SQL Links driver or is using the ODBC socket to communicate with a third-party ODBC driver. If the connection uses the STANDARD driver, IsSQLBased is false.


TDatabase::KeepConnection

TDatabase	See also	Example

Specifies whether an application remains connected to a database even if no datasets are open.

__property bool KeepConnection = {read=FKeepConnection, write=SetKeepConnection, default=1};

Description

Use KeepConnection to specify whether an application remains connected to a database even if no datasets are currently open. When KeepConnection is true (the default) the connection is maintained. For connections to remote database servers, or for applications that frequently open and close datasets, set KeepConnection to true to reduce network traffic, speed up applications, and avoid logging in to the server each time the connection is reestablished.

When KeepConnection is false a connection is dropped when there are no open datasets. Dropping a connection releases system resources allocated to the connection, but if a dataset is later opened that uses the database, the connection must be reestablished and initialized.

Note:	The KeepConnection setting for temporary database components created automatically as needed is determined by the KeepConnections property of TSession.


TDatabase::Locale

TDatabase	See also

Identifies the Borland Database Engine (BDE) language driver for the database component.

__property void * Locale = {read=FLocale};

Description

Examine Locale to determine the BDE language driver used by the database component. Applications that make direct calls to the BDE may also need to pass Locale information as an API function parameter.

Language driver information may also be available as one of the values in the Params property when a database component is using a BDE alias.

Note:	Do not use this property unless an application requires BDE functionality not available through standard C++Builder components.


TDatabase::LoginPrompt

TDatabase	See also	Example

Indicates whether or not to display a standard Login dialog box when establishing a database connection.

__property bool LoginPrompt = {read=FLoginPrompt, write=FLoginPrompt, default=1};

Description

Use LoginPrompt to control the login method for remote database connections. If true, (the default), either the standard C++Builder Login dialog box opens when the application attempts to connect to a database, or the OnLogin event is called if one is provided for the application.

The standard Login dialog box prompts for a valid user name and password. If the entries provided by the user are not valid, the connection fails. Applications that provide an OnLogin event must make sure that the event provides these values to the server.

If an application sets LoginPrompt to false, then user name and password values must be supplied as USER NAME and PASSWORD parameters in the Params property.

Note:	Storing hard-coded user name and password entries in the Params property or in code for an OnLogin event can compromise server security.


TDatabase::Params

TDatabase	See also

Contains database connection parameters for the Borland Database Engine (BDE) alias associated with the database component.

__property Classes::TStrings* Params = {read=FParams, write=SetParams};

Description

Use Params to examine or specify database connection parameters, such as path name, server name, schema-caching size, language driver, user name, and password. Actual parameters in Params differ depending on the current BDE alias and driver for the database component.

Note:	Applications can use Params to override the default settings supplied by a BDE alias.

Params is a list of string items, each representing a different database connection parameter. If the AliasName property specifies a valid BDE alias, then Params automatically contains the parameters defined for that alias. If, instead of providing an alias, an application uses the DriverName property to provide a local alias, the application must provide Params values directly.

Tip:	At design time double-click a TDatabase component to invoke the Database editor and set Params.


TDatabase::Session

TDatabase	See also

Points to the session component with which this database component is associated.

__property TSession* Session = {read=FSession};

Description

Use Session to determine the session component that controls the database component. By default, a database component is associated with the default session component, Session, that is automatically created for all database applications. To assign a database component to a different session in a multi-threaded application, specify the name of a different session component in the SessionName property.


TDatabase::SessionAlias

TDatabase	See also

Specifies whether or not a database component is using a session alias.

__property bool SessionAlias = {read=FSessionAlias, nodefault};

Description

Examine SessionAlias to see if a database component is using a session alias. If SessionAlias is true, a session alias is in use. If false, a session alias is not in use.

A session alias is automatically created for a database component if it

•	Uses the DriverName and Params properties instead of the AliasName property, and the Params property contains any parameters.

•	Overrrides Params values supplied by a BDE alias in AliasName.

A session alias may also be created if an application permits the user to log into a server using a different user name than the one specified in the Params property.

A session alias exists only while the application is running. It is not stored in the BDE configuration file, and cannot be accessed from outside the application.


TDatabase::SessionName

TDatabase	See also 	Example

Identifies the name of the session used by this database component.

__property System::AnsiString SessionName = {read=FSessionName, write=SetSessionName};

Description

Use SessionName to specify the session with which a database component is associated. If SessionName is blank, a database component is automatically associated with the default session, Session.

To associate a database component with a different session in a database application SessionName must matches the SessionName property of an existing session component.


TDatabase::Temporary

TDatabase	See also	Example

Indicates whether a database component is a temporary one, created by the system as needed, or a persistent one explicitly created, managed, and freed within the application.

__property bool Temporary = {read=FTemporary, write=FTemporary, nodefault};

Description

Examine Temporary to determine if a database component is a temporary one, created by the system as needed, or a persistent one explicitly created, managed, and freed within the application. Temporary is true if the system created the component, false otherwise.

A temporary database component is created when a dataset is opened and the dataset is not already associated with an existing database component. If Temporary remains true, then a temporary database component is freed when the dataset is closed. An application can prevent the destruction of a temporary database component by setting Temporary to false while the dataset is active, but the application is then responsible for closing the database when it is no longer needed.


TDatabase::TraceFlags

TDatabase	See also

Specifies the database operations to track with the SQL Monitor at runtime.

enum TTraceFlag { tfQPrepare, tfQExecute, tfError, tfStmt, tfConnect, tfTransact, tfBlob, tfMisc, tfVendor, tfDataIn, tfDataOut };

typedef Set<TTraceFlag, tfQPrepare, tfDataOut>  TTraceFlags;

__property TTraceFlags TraceFlags = {read=GetTraceFlags, write=SetTraceFlags, nodefault};

Description

Use TraceFlags to specify which database operations the SQL Monitor should track in an application at runtime. TraceFlags is only meaningful for the SQL Monitor, which is provided to enable performance tuning and SQL debugging when working with remote SQL database servers.

Note:	Normally trace options are set from the SQL Monitor rather than setting TraceFlags in application code.

The value of a session component’s TraceFlags property determines the initial settings of the TraceFlags property for database components associated with the session.

The TTraceFlags type defines the individual values that can be included in the TraceFlags property. The following table summarizes those values:

Values	Meaning

tfQPrepare	Monitor Prepare statements.

tfQExecute	Monitor ExecSQL statements.

tfError	Monitor server error messages. Such messages may include an error code.

tfStmt	Monitor all SQL statements.

tfConnect	Monitor database connect and disconnect operations, including allocation of connection handles, and freeing connection handles.

tfTransact	Monitor transaction statements, such as StartTransaction, Commit, and Rollback.

tfBlob	Monitor operations on blob data types.

tfMisc	Monitor any statements not covered by other flag options.

tfVendor	Monitor direct API function calls to the database server.

tfDataIn	Monitor data received from a server.

tfDataOut	Monitor data sent to a server.

Because TraceFlags is a set property, an application can specify different combinations of flags to monitor different combinations of statements. For example, the following statement limits monitoring to database connections and SQL statement preparation:

TraceFlags << tfConnect << tfQPrepare;


TDatabase::TransIsolation

TDatabase	See also	Example

Specifies the transaction isolation level for transactions managed by the Borland Database Engine (BDE).

__property TTransIsolation TransIsolation = {read=FTransIsolation, write=FTransIsolation, default=1};

Description

Use TransIsolation to specify the transaction isolation level for database transactions managed by the BDE. Transaction isolation level determines how a transaction interacts with other simultaneous transactions when they work with the same tables, and how much a transaction sees of the work performed by other transactions.

Note:	Applications that use passthrough SQL for handling transactions must pass a transaction isolation level directly to the database server using the appropriate SQL statement.

TransIsolation can be any one of the three values summarized in the following table:

Isolation level	Meaning

tiDirtyRead	Permits reading of uncommitted changes made to the database by other simultaneous transactions. Uncommitted changes are not permanent, and might be rolled back (undone) at any time. At this level a transaction is least isolated from the effects of other transactions.

tiReadCommitted	Permits reading of committed (permanent) changes made to the database by other simultaneous transactions. This is the default TransIsolation property value.

tiRepeatableRead	Permits a single, one-time reading of the database. The transaction cannot see any subsequent changes made by other simultaneous transactions. This isolation level guarantees that once a transaction reads a record, its view of that record does not change unless it makes a modification to the record itself. At this level, a transaction is most isolated from other transactions.

Different database servers support different levels of transaction isolation. If an application sets TransIsolation to an unsupported level for a remote SQL server, the BDE uses the next highest level supported by that server. The following table summarizes the isolation levels supported by the servers recognized by the BDE:

Server	Specified Level	Actual Level
Oracle	tiDirtyRead tiReadCommitted tiRepeatableRead	tiReadCommitted tiReadCommitted tiRepeatableRead (READONLY)
Sybase, MS-SQL	tiDirtyRead tiReadCommitted tiRepeatableRead	tiReadCommitted tiReadCommitted Not supported
DB2	tiDirtyRead tiReadCommitted tiRepeatableRead	tiDirtyRead tiReadCommitted tiRepeatableRead
Informix	tiDirtyRead tiReadCommitted tiRepeatableRead	tiDirtyRead tiReadCommitted tiRepeatableRead
InterBase	tiDirtyRead tiReadCommitted tiRepeatableRead	tiReadCommitted tiReadCommitted tiRepeatableRead
Paradox, dBASE, Access, FoxPro	tiDirtyRead tiReadCommitted tiRepeatableRead	tiDirtyRead Not supported Not supported
Note:	For local transactions against Paradox and dBASE, TransIsolation must be set to tiDirtyRead. Otherwise, an exception is raised.

If an application uses ODBC to interface with a server, the ODBC driver must also support the isolation level. For more information about supported isolation levels, see the documentation for the ODBC driver in question.


TDatabase events

TDatabase	Alphabetically	Legend

In TDatabase

OnLogin


TDatabase events

TDatabase	By object	Legend

OnLogin


TDatabase::OnLogin

TDatabase	See also

Occurs when an application connects to a database.

__property TLoginEvent OnLogin = {read=FOnLogin, write=FOnLogin};

Description

Write an OnLogin event handler to take specific actions when an application attempts to connect to a database. By default, a database login is required. The current USERNAME is read from the Params property, and a standard Login dialog box opens. The dialog prompts for a user name and password combination, and then uses the values entered by the user to set the USERNAME and PASSWORD values in the Params property. These values are then passed to the remote server.

Applications that provide alternative OnLogin event handlers must set the USERNAME and PASSWORD values in LoginParams. LoginParams is a temporary string list and is freed automatically when no longer needed.


TDatabase methods

TDatabase	Alphabetically

In TDatabase

~TDatabase

ApplyUpdates

Close

CloseDataSets

Commit

FlushSchemaCache

Open

Rollback

StartTransaction

TDatabase

ValidateName

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDatabase methods

TDatabase	By object

~TDatabase

ApplyUpdates

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

CloseDataSets

Commit

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FlushSchemaCache

Free

FreeInstance

FreeNotification

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

Rollback

SafeCallException

StartTransaction

TDatabase

ValidateName


TDatabase::ApplyUpdates

TDatabase	See also

Posts pending cached updates for specified datasets to the database server.

void __fastcall ApplyUpdates(TDBDataSet* const * DataSets, const int DataSets_Size);

Description

Call ApplyUpdates to post pending cached updates for a specific set of open datasets to the database server. ApplyUpdates is only meaningful if the CachedUpdates property of a specified dataset is true.

DataSets is a list of dataset names specifying the datasets for which to post pending updates. DataSets need not list every currently open dataset. For each listed dataset ApplyUpdates calls the dataset’s ApplyUpdates and CommitUpdates methods to post that dataset’s pending cached updates.

Applying updates is a two-phase process that takes place within the context of the database component’s transaction control. When an application calls ApplyUpdates, the following events take place:

1	A database transaction starts.

2	Cached updates are written to the database (Phase 1).

If the database write is successful:

1•	Database changes are committed, ending the transaction.

2•	Cached updates are committed, clearing the internal cache buffer (Phase 2).

If the database write fails database changes are rolled back, ending the transaction.

The two-phased approach allows for effective error recovery, especially when updating multiple and interrelated datasets (for example, the datasets associated with a master/detail form).


TDatabase::Close

TDatabase	See also	Example

Closes all open datasets associated with the database component and disconnects from the database server.

void __fastcall Close(void);

Description

Call Close to disconnect from a database server. Disconnecting frees system resources allocated to the connection.

Note:	Close is called automatically when there are no more open datasets associated with the database component and the KeepConnection property is false. A database connection can also be closed by setting the Connected property to false.


TDatabase::CloseDataSets

TDatabase	See also	Example

Closes all datasets associated with the database component without disconnecting from the database server.

void __fastcall CloseDataSets(void);

Description

Call CloseDataSets to close all active datasets without disconnecting from the database server. Ordinarily, when an application calls Close, all datasets are closed, and the connection to the database server is dropped. Calling CloseDataSets instead of Close ensures that an application can close all active datasets without having to reconnect to the database server at a later time.


TDatabase::Commit

TDatabase	See also 	Example

Permanently stores updates, insertions, and deletions of data associated with the current transaction, and ends the current transactions.

void __fastcall Commit(void);

Description

Call Commit to permanently store to the database server all updates, insertions, and deletions of data associated with the current transaction and then end the transaction. The current transaction is the last transaction started by calling StartTransaction.

Note:	Before calling Commit, an application may check the status of the InTransaction property. If an application calls Commit and there is no current transaction, an exception is raised.


TDatabase::TDatabase

TDatabase	See also

Creates an instance of a TDatabase component.

__fastcall virtual TDatabase(Classes::TComponent* AOwner);

Description

Call TDatabase to instantiate a database component at runtime. An application can create a database component in order to control the component’s existence and set its properties and events, or an application can let C++Builder create temporary database components as needed at runtime.

TDatabase instantiates a database component and:

•	Sets the Session property to the active session.

•	Sets the SessionName property to the name of the active session component.

•	Adds this component to the list of database components for the session.

•	Creates an empty list of dataset components for the DataSets property.

•	Creates an empty string list for the Params property.

•	Sets the LoginPrompt property and the KeepConnection property to true.

•	Sets the Locale property to the locale of the session.

•	Sets the TransIsolation property to tiReadCommitted.


TDatabase::~TDatabase

TDatabase	See also

Destroys the instance of a database component.

__fastcall virtual ~TDatabase(void);

Description

Do not call ~TDatabase directly in an application. Instead, call Free, which verifies that the database component is not already freed before calling ~TDatabase.

~TDatabase closes all active datasets and disconnects from the database server, if necessary. It then frees the string resources allocated for the Params and DataSets properties before calling its parent object’s destructor.


TDatabase::FlushSchemaCache

TDatabase	See also

Flushes the cached schema information for a table.

void __fastcall FlushSchemaCache(const System::AnsiString TableName);

Description

Call FlushSchemaCache if the schema information for an SQL table is changed (for example, because a field, index, or table is added to or dropped from a database).

When an application opens an SQL table, schema information that describes the field names, field types, and index information is stored in memory. If an application changes the schema for an SQL table, it should call FlushSchemaCache to update the schema information in memory.


TDatabase::Open

TDatabase	See also	Example

Connects to a database server.

void __fastcall Open(void);

Description

Call Open to establish a connection to a local or remote database server. Open verifies that the database specified by the DatabaseName or Directory properties exists, and that the user name and password are valid. If so, it connects to the database. If an OnLogin event exists for the database component, it is executed. Otherwise, the default Login dialog box appears.

Note:	Setting Connected to true also connects to the database server.


TDatabase::Rollback

TDatabase	See also 	Example

Cancels all updates, insertions, and deletions for the current transaction and ends the transaction.

void __fastcall Rollback(void);

Description

Call Rollback to cancel all updates, insertions, and deletions for the current transaction and to end the transaction. The current transaction is the last transaction started by calling StartTransaction.

Note:	Before calling Rollback, an application may check the status of the InTransaction property. If an application calls Rollback and there is no current transaction, an exception is raised.


TDatabase::StartTransaction

TDatabase	See also 	Example

Begins a new transaction against the database server.

void __fastcall StartTransaction(void);

Description

Call StartTransaction to begin a new transaction against the database server. Before calling StartTransaction, an application should check the status of the InTransaction property and adjust the setting of the TransIsolation property as desired. If InTransaction is true, indicating that a transaction is already in progress, a subsequent call to StartTransaction without first calling Commit or Rollback to end the current transaction raises an exception.

Updates, insertions, and deletions that take place after a call to StartTransaction are held by the server until an application calls Commit to save the changes or Rollback is to cancel them.


TDatabase::ValidateName

TDatabase	See also 	Example

Raises an exception if a specified database is already open in the active session.

void __fastcall ValidateName(const System::AnsiString Name);

Description

Call ValidateName to prevent duplicate access to a database from within a single session. Name is a string containing the name of the database to test. If the database is already open, ValidateName raises the EDatabaseError exception. If the database is not open, the procedure returns, and the application continues processing.

Note:	Most applications should not need to call this method directly. It is called automatically each time a database is opened.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


THTTPDataLink

Hierarchy	Properties	Methods	See also

THTTPDataLink helps TDSTableProducer manage its link to the data source.

Unit

dbweb

Description

THTTPDataLink is tailored to work with a TDSTableProducer object. It should only be used by the TDSTableProducer class.


THTTPDataLink properties

THTTPDataLink	Alphabetically	Legend

In THTTPDataLink

DefaultFields

FieldCount

Fields

SparseMap

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


THTTPDataLink properties

THTTPDataLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

DefaultFields

Editing

FieldCount

Fields

ReadOnly

RecordCount

SparseMap


THTTPDataLink::DefaultFields

THTTPDataLink	See also

Indicates whether the associated table producer uses dynamically generated field components.

__property bool DefaultFields = {read=GetDefaultFields, nodefault};

Description

Read DefaultFields to determine whether the image of the table will display dynamically generated field components or persistent field components. If DefaultFields is true, the fields in the image of the table will represent dynamically allocated field components. If DefaultFields is false, the image will be built from persistent field components.

If the image of the datasouce is built from persistent field components, it may not show all of the fields that are present in the underlying database table.


THTTPDataLink::FieldCount

THTTPDataLink	See also

Specifies the number of entries in the Fields array.

__property int FieldCount = {read=FFieldCount, nodefault};

Description

Use FieldCount when iterating over all the field components in the Fields property. FieldCount is the number of columns shown in the image of the datasource. The Fields array can contain undefined field components, which correspond to field components that are not in the dataset, such as calculated fields.


THTTPDataLink::Fields

THTTPDataLink	See also

Lists all the field components from the dataset that may be shown in the image of the datasource.

__property Db::TField* Fields[int I] = {read=GetFields};

Description

Use Fields to access field components by index. Fields[0] is the first field component, Fields[1] is the second field component, and so on. If the SparseMap property is true, Fields may contain undefined field components. For these entries, Fields returns NULL.

TDSTableProducer uses Fields to keep track of all field components that are part of its dataset. Whenever necessary, TDSTableProducer reconciles the field bindings of its columns with the field components in Fields.


THTTPDataLink::SparseMap

THTTPDataLink	See also

Indicates whether the associated table producer has customized the number or order of the fields that appear in the table.

__property bool SparseMap = {read=FSparseMap, write=FSparseMap, nodefault};

Description

Read SparseMap to determine whether Fields is a simple reflection of the underlying dataset. TDSTableProducer sets SparseMap when it builds the field map. SparseMap is false if TDSTableProducer builds a default field map directly from the dataset. SparseMap is true if the number or order of the fields has been changed from the default. When SparseMap is true, the Fields array may contain undefined fields.


THTTPDataLink methods

THTTPDataLink	Alphabetically	Legend

In THTTPDataLink

~THTTPDataLink

ActiveChanged

AddMapping

ClearMapping

DataSetChanged

DataSetScrolled

EditingChanged

FocusControl

GetMappedIndex

LayoutChanged

Modified

RecordChanged

Reset

THTTPDataLink

UpdateData

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTTPDataLink methods

THTTPDataLink	By object	Legend

~THTTPDataLink

ActiveChanged

AddMapping

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearMapping

DataSetChanged

DataSetScrolled

DefaultHandler

Dispatch

Edit

EditingChanged

FieldAddress

FocusControl

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMappedIndex

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LayoutChanged

MethodAddress

MethodName

Modified

NewInstance

RecordChanged

Reset

SafeCallException

THTTPDataLink

UpdateData

UpdateRecord


THTTPDataLink::ActiveChanged

THTTPDataLink	See also

Informs the table producer when the Active property changes.

virtual void __fastcall ActiveChanged(void);

Description

Applications cannot call the ActiveChanged method directly. Changes in the Active property trigger this procedure. ActiveChanged calls the LinkActive method of the TDSTableProducer, which recomputes the layout for the table if the dataset has just become active.


THTTPDataLink::AddMapping

THTTPDataLink	See also

Adds a field component to the end of the Fields array.

bool __fastcall AddMapping(const System::AnsiString FieldName);

Description

Applications should not call AddMapping directly, because this would cause the Fields array to become out of sync with the THTMLTableColumns object used by TDSTableProducer. TDSTableProducer calls AddMapping iteratively to set up the Fields array so that it corresponds to the columns in the table image.


THTTPDataLink::ClearMapping

THTTPDataLink	See also

Empties the Fields array and frees any associated memory.

void __fastcall ClearMapping(void);

Description

Applications should not call ClearMapping directly, because this would cause the Fields array to become out of sync with the THTMLTableColumns object used by TDSTableProducer. TDSTableProducer calls ClearMapping before rebuilding the Fields list, every time the column mapping changes.


THTTPDataLink::THTTPDataLink

THTTPDataLink	See also

Creates an instance of THTTPDataLink.

__fastcall THTTPDataLink(TDSTableProducer* DSTableProducer);

Description

Applications should not create instances of THTTPDataLink. TDSTableProducer instantiates a THTTPDatalink object from its own constructor.


THTTPDataLink::DataSetChanged

THTTPDataLink	See also

Informs the associated table producer of changes to the dataset.

virtual void __fastcall DataSetChanged(void);

Description

Applications can not call DataSetChanged directly. Changes to the contents of the dataset trigger this method automatically.


THTTPDataLink::DataSetScrolled

THTTPDataLink	See also

Ignores scrolling events on the dataset.

virtual void __fastcall DataSetScrolled(int Distance);

Description

Applications can not call DataSetScrolled directly. This method overrides the parent class’s method so that TDSTableProducer can ignore scrolling events that would occur if the TDSTableProducer were a visual control.


THTTPDataLink::~THTTPDataLink

THTTPDataLink	See also

Destroys an instance of THTTPDataLink.

__fastcall virtual ~THTTPDataLink(void);

Description

Do not call ~THTTPDataLink directly in an application. The TDSTableProducer object that owns the THTTPDataLink frees the THTTPDataLink from its own destructor.

~THTTPDataLink frees up the memory used by the Fields array before calling the parent class’s destructor.


THTTPDataLink::EditingChanged

THTTPDataLink	See also

Ignores changes to the editing state of the dataset.

virtual void __fastcall EditingChanged(void);

Description

Applications can not call EditingChanged directly. This method ignores changes to the editing state of the dataset, which are irrelevant to TDSTableProducer.


THTTPDataLink::FocusControl

THTTPDataLink	See also

Discards requests to set focus to the indicated field.

virtual void __fastcall FocusControl(Db::TFieldRef Field);

Description

TDSTableProducer does not support the concept of focus assigned to an individual field. FocusControl discards requests sent through the data source to assign focus to an individual field.


THTTPDataLink::GetMappedIndex

THTTPDataLink	See also

Returns the index of the field component in the dataset that corresponds to the index of the field component within the Fields array.

int __fastcall GetMappedIndex(int ColIndex);

Description

Applications can not call GetMappedIndex directly. GetMappedIndex takes ColIndex, the index of a field component in the Fields array, and returns the corresponding index of the field component in the dataset.


THTTPDataLink::LayoutChanged

THTTPDataLink	See also

Informs TDSTableProducer of changes in the layout of columns at design time.

virtual void __fastcall LayoutChanged(void);

Description

Applications can not call the LayoutChanged method directly. LayoutChanged is triggered automatically by changes to the layout of columns at design time. LayoutChanged instructs the TDSTableProducer object to recompute the layout for the table.


THTTPDataLink::Modified

THTTPDataLink	See also

Tracks changes to the data which have not been written to the current record in the database.

void __fastcall Modified(void);

Description

Call Modified before changing the value of a field in the current record of the dataset. It is not necessary to call Modified if the changes are written directly to the field components indexed by the Fields property.


THTTPDataLink::RecordChanged

THTTPDataLink	See also

Ignores changes to the contents of the current record or field of the data source.

virtual void __fastcall RecordChanged(Db::TField* Field);

Description

Applications can not call RecordChanged directly. This method ignores changes to the contents of the current record in the data source, which are irrelevant to the TDSTableProducer.


THTTPDataLink::Reset

THTTPDataLink	See also

Cancels any pending edits to the dataset that have not been written to the current record in the database.

void __fastcall Reset(void);

Description

Applications can not call Reset directly. Descendants of TDSTableProducer can implement a method or user interface that triggers the cancellation of pending edits.


THTTPDataLink::UpdateData

THTTPDataLink	See also

Discards requests to post changes to the dataset.

virtual void __fastcall UpdateData(void);

Description

TDSTableProducer produces an HTML image of a dataset. It is not a control that can be used to edit the data in the dataset. UpdateData discards requests sent through the data source to post edits to the dataset.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


TDataLink

Hierarchy	Properties	Methods	See also

TDataLink is a helper class used by data-aware objects to coordinate the actions of TDataSource and TDataSet, and to respond to data events.

Unit

db

Description

Use TDataLink or one of its descendants in any data-aware object that implements a DataSource property to represent its link to a dataset or that needs to respond to data events.

The constructor of the data-aware object should call the constructor of TDataLink, and initialize any relevant properties. The data-aware object can then link to a TDataSource by using the DataSource property of the TDataLink.

Data-aware objects that link to a single field in a dataset should use a TFieldDataLink instead.


TDataLink properties

TDataLink	Alphabetically	Legend

In TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TDataLink properties

TDataLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TDataLink::Active

TDataLink	See also

Specifies whether or not the dataset that TDataLink manages is active.

__property bool Active = {read=FActive, nodefault};

Description

Read Active to determine whether the dataset for this TDataLink is Active. When Active is false, the dataset is closed, and the dataset cannot read data from or write data to the database. When Active is true, data can be read from and written to the dataset.


TDataLink::ActiveRecord

TDataLink	See also

Specifies the index of the current record within the internal set of records buffer maintained by the dataset for the Owner of the TDataLink object.

__property int ActiveRecord = {read=GetActiveRecord, write=SetActiveRecord, nodefault};

Description

Use ActiveRecord to discover or set the current record in the set of one or more records managed by the dataset. The set of records managed by the dataset corresponds to the number of records from the dataset visible at one time. For example, when the TDataLink object is owned by a data-aware grid, the set of records managed by the dataset corresponds to the number of rows shown by the grid, and the ActiveRecord represents the current row.


TDataLink::BufferCount

TDataLink	See also

Specifies the size of the set of records maintained by the dataset for the Owner of the TDataLink object.

__property int BufferCount = {read=FBufferCount, write=SetBufferCount, nodefault};

Description

Set BufferCount to tell the dataset how many records to buffer together to service the owner of the TDataLink object. For example, a data-aware grid sets BufferCount to the number of rows visible in the grid.

Read BufferCount to iterate through all the records buffered by the dataset for the owner of the TDataLink object. For example, A data-aware object can paint itself by cycling through the set of records, moving the ActiveRecord to visit each record in turn.


TDataLink::DataSet

TDataLink	See also

Specifies the TDataSet object that represents the data that this TDataLink is tracking.

__property TDataSet* DataSet = {read=GetDataSet};

Description

Read DataSet to determine the dataset that this TDataLink is helping to manage. The TDataLink responds to data events that are received by the DataSet, and makes changes to the dataset on behalf of the object that owns the TDataLink object.


TDataLink::DataSource

TDataLink	See also

Specifies the TDataSource object that the Owner of the TDataLink uses to connect to the dataset.

__property TDataSource* DataSource = {read=FDataSource, write=SetDataSource};

Description

Use DataSource to determine or set the TDataSource object that connects to the dataset. TDataLink responds to data events that the DataSource receives.

Note:	To implement the DataSource property of a data-aware object which owns a TDataLink or its descendant, create a method that gets or sets the DataSource property of the TDataLink-derived member.


TDataLink::DataSourceFixed

TDataLink	See also

Indicates whether the DataSource property can be set.

__property bool DataSourceFixed = {read=FDataSourceFixed, write=FDataSourceFixed, nodefault};

Description

Use DataSourceFixed to determine whether the DataSource property can be changed. By default, DataSourceFixed is false, allowing the DataSource property to be changed.

When there is a chance that an asynchronous event might change the DataSource before an operation completes, set DataSourceFixed to true before performing the operation to ensure that the DataSource is constant throughout the operation. After the data operation is complete, DataSourceFixed can be set back to false.

Set DataSourceFixed to prevent the DataSource of a data-aware object that owns the TDataLink from being changed once it is set.


TDataLink::Editing

TDataLink	See also

Indicates whether the DataSource is in edit mode.

__property bool Editing = {read=FEditing, nodefault};

Description

Read Editing to determine whether the DataSource is inserting a new record into the dataset, or modifying the current record. To change the dataset into edit mode, and hence the Editing property to true, use the Edit method.


TDataLink::ReadOnly

TDataLink	See also

Indicates whether the dataset for this TDataLink can be modified.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, nodefault};

Description

Use ReadOnly to determine whether the dataset for this TDataLink can be modified. Setting ReadOnly to true causes any subsequent calls to the Edit method to fail, and changes the DataSource out of an editing state if it is in one. Setting ReadOnly to false enables changes to the data in the dataset.


TDataLink::RecordCount

TDataLink	See also

Indicates the number of records in the internal record buffer maintained for the Owner of the TDataLink object by the dataset.

__property int RecordCount = {read=GetRecordCount, nodefault};

Description

Read RecordCount to determine the number of actual records in the buffer maintained by the dataset for the Owner of this TDataLink.

In most cases, RecordCount is the same as BufferCount. RecordCount indicates the number of records actually in the record buffer of the dataset, as opposed to the number of records that the dataset can possibly maintain. For example, a data-aware grid with four rows could have one record actually showing data. In this case, BufferCount would be 4, while RecordCount would be 1.


TDataLink methods

TDataLink	Alphabetically	Legend

In TDataLink

~TDataLink

ActiveChanged

CheckBrowseMode

DataSetChanged

DataSetScrolled

Edit

EditingChanged

FocusControl

LayoutChanged

RecordChanged

TDataLink

UpdateData

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDataLink methods

TDataLink	By object	Legend

~TDataLink

ActiveChanged

Assign

CheckBrowseMode

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DataSetChanged

DataSetScrolled

DefaultHandler

Dispatch

Edit

EditingChanged

FieldAddress

FocusControl

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LayoutChanged

MethodAddress

MethodName

NewInstance

RecordChanged

SafeCallException

TDataLink

UpdateData

UpdateRecord


TDataLink::ActiveChanged

TDataLink	See also

Responds to changes in the Active property.

virtual void __fastcall ActiveChanged(void);

Description

The ActiveChanged method defined by TDataLink merely provides an interface for a method that can respond to changes in the Active property. Derived objects that do not need to respond to such changes can allow the inherited method to ignore them.


TDataLink::CheckBrowseMode

TDataLink	See also

Allows the data-aware object to respond just before an event that changes the dataset.

virtual void __fastcall CheckBrowseMode(void);

Description

The CheckBrowseMode method defined by TDataLink merely provides an interface for a method that can update any state information just before a change to the dataset occurs. Derived objects that do not need to respond to these events can allow the inherited method to ignore them.


TDataLink::TDataLink

TDataLink	See also

Creates an instance of TDataLink.

__fastcall TDataLink(void);

Description

TDataLink is called from the constructor of any data-aware object that uses a TDataLink to implement its DataSource property. When instantiating a TDataLink object, call the constructor indirectly using the new keyword.

After calling the parent object’s constructor, TDataLink initializes the BufferCount property to 1. Data-aware objects that use a TDataLink object to manage their link to a DataSource should change the BufferCount property to the number or records they represent, after calling the parent object’s constructor.


TDataLink::DataSetChanged

TDataLink	See also

Responds to changes in the dataset.

virtual void __fastcall DataSetChanged(void);

Description

DataSetChanged responds to changes to the contents of the dataset. Anything that changes the contents of the dataset, whether it is editing the data, inserting or deleting records, or changing the key triggers this method. Changes specific to the representation of the data within the data-aware object, such as scrolling the dataset or changing the layout of data elements within the object, also trigger this method. DataSetChanged simply calls RecordChanged. Derived classes can override this procedure to make additional adjustments to changes in the dataset.


TDataLink::DataSetScrolled

TDataLink	See also

Allows a response to scrolling the representation of the dataset within the data-aware object.

virtual void __fastcall DataSetScrolled(int Distance);

Description

DataSetScrolled ignores the Distance parameter and calls DataSetChanged. Derived classes can override this procedure to make additional adjustments when the dataset scrolls.


TDataLink::~TDataLink

TDataLink	See also

Destroys an instance of TDataLink.

__fastcall virtual ~TDataLink(void);

Description

Do not call ~TDataLink directly in an application. Instead, use the delete keyword, which takes an indirect reference to a TDataLink object.

Before calling the parent object’s destructor, ~TDataLink removes any reference to the TDataLink from the data source object.

The TDataLink object should be destroyed in the destructor of its Owner, where that Owner creates the TDataLink from its constructor.


TDataLink::Edit

TDataLink	See also

Attempts to drive the data source into an editing state if it is not already in one.

bool __fastcall Edit(void);

Description

Use Edit to try to ensure that the current record can be modified. A return value of true indicates that the data source was already in an editing state, or that it was successfully changed to allow editing. A return value of false indicates that the data source could not be changed to allow editing. For example, if the ReadOnly property is true, Edit will not allow editing and will return false.


TDataLink::EditingChanged

TDataLink	See also

Responds to changes in the editing state of the data source.

virtual void __fastcall EditingChanged(void);

Description

The EditingChanged method defined by TDataLink merely provides an interface for a method that can respond to changes in the editing state of the data source. EditingChanged is called immediately after the Editing property has changed its value. Derived objects that do not need to respond to such changes can allow the inherited method to ignore them.


TDataLink::FocusControl

TDataLink	See also

Provides the interface for a method to force focus to the data-aware component associated with the TDataLink.

virtual void __fastcall FocusControl(TFieldRef Field);

Description

The FocusControl method defined by TDataLink merely provides an interface for a method that can force the input focus to a data-aware object associated with the TDataLink. Derived objects that do not need this capability can allow the inherited method to ignore the request.


TDataLink::LayoutChanged

TDataLink	See also

Responds to changes in the representation of the data by the data-aware object.

virtual void __fastcall LayoutChanged(void);

Description

The LayoutChanged method simply calls the DataSetChanged method. LayoutChanged is intended to provide an interface for a method that can respond after changes in the representation of the data by the data-aware object. An example of such a change would be changing the number or order of the columns in a TCustomDBGrid.


TDataLink::RecordChanged

TDataLink	See also

Responds to changes in the contents of the current record or field of the dataset.

virtual void __fastcall RecordChanged(TField* Field);

Description

The RecordChanged method defined by TDataLink merely provides an interface for a method that can respond to changes to the contents of the current record. RecordChanged is called after changes have been posted to the current record in the dataset, and from DataSetChanged.

The Field parameter indicates which field of the current record has changed in value. If Field is NULL, any number of fields within the current record may have changed.

Derived objects that do not need to respond to such changes can allow the inherited method to ignore them.


TDataLink::UpdateData

TDataLink	See also

Provides an interface for writing edits to a record in the dataset.

virtual void __fastcall UpdateData(void);

Description

The UpdateData method defined by TDataLink merely provides an interface for a method that writes updates to the current record in the dataset while avoiding calls to RecordChanged that posting the changes may trigger. Derived objects that do not need to write edits to the dataset can allow the inherited method to do nothing.


TDataLink::UpdateRecord

TDataLink	See also

Responds to notifications that edits should be posted to the dataset.

void __fastcall UpdateRecord(void);

Description

UpdateRecord calls UpdateData after guarding against calls to RecordChanged which may arise while UpdateData is executing.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent


TDataModule

Hierarchy	Properties	Methods	Events	See also

TDataModule centralizes the handling of nonvisual components in an application.

Unit

forms

Description

Use a TDataModule object in an application to provide a location for centralized handling of nonvisual components. Typically these are data access components (TSession, TSessionList, TDatabase, TTable, TQuery, TStoredProc, and TBatchMove), but they can also be other nonvisual components, such as TTimer, TOpenDialog, TImageList, or TOleContainer).

At design time a TDataModule object provides a visual container into which a developer can place nonvisual components, set their properties, and write event handlers for them. To create a data module at design time, choose File|New Data Module.

In the unit file for the data module a developer may also place any business rules that are to be applied to the application.

To make the data module available to another unit in the application, select that unit, then choose File|Use Unit to add the data module to the uses clause for the unit.


TDataModule properties

TDataModule	Alphabetically	Legend

In TDataModule

DesignOffset

DesignSize

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDataModule properties

TDataModule	By object	Legend

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

DesignInfo

DesignOffset

DesignSize

Name

Owner

Tag

VCLComObject


TDataModule::DesignOffset

TDataModule	See also

Specifies the design offset for the data module at design time.

__property tagPOINT DesignOffset = {read=FDesignOffset, write=FDesignOffset};

Description

Specifies the design offset for the data module at design time. An application should never need to set this value.


TDataModule::DesignSize

TDataModule	See also

Specifies the design size for the data module at design time.

__property tagPOINT DesignSize = {read=FDesignSize, write=FDesignSize};

Description

Specifies the design size for the data module at design time. An application should never need to set this value.


TDataModule events

TDataModule	Alphabetically	Legend

In TDataModule

OnCreate

OnDestroy


TDataModule events

TDataModule	By object	Legend

OnCreate

OnDestroy


TDataModule::OnCreate

TDataModule	See also

Occurs when an application instantiates a data module.

__property Classes::TNotifyEvent OnCreate = {read=FOnCreate, write=FOnCreate};

Description

Write an OnCreate event handler to take specific actions when an application instantiates a data module. For example, if a data module contains database and dataset components, an application may establish a database connection immediately. If the data module contains timers, the application may initialize them.


TDataModule::OnDestroy

TDataModule	See also

Occurs when the data module is about to be destroyed.

__property Classes::TNotifyEvent OnDestroy = {read=FOnDestroy, write=FOnDestroy};

Description

Write an OnDestroy event handler to take specific actions when an application frees a data module. For example, if the unit code for data module instantiates any objects of its own, such as string lists, the OnDestroy event handler can be used to free those objects.


TDataModule methods

TDataModule	Alphabetically

In TDataModule

~TDataModule

CreateNew

TDataModule

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDataModule methods

TDataModule	By object

~TDataModule

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateNew

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TDataModule


TDataModule::TDataModule

TDataModule	See also

Creates an instance of a data module.

__fastcall virtual TDataModule(Classes::TComponent* AOwner);

Description

Call TDataModule to instantiate a data module at runtime if it was not created at design time. TDataModule calls CreateNew. If an error occurs, an exception is raised. Otherwise TDataModule calls the OnCreate event handler for the data module if one is assigned to it.


TDataModule::TDataModule
TDataModule::CreateNew

TDataModule	See also

Creates an instance of a data module and registers with the global screen object.

__fastcall virtual TDataModule(Classes::TComponent* AOwner);

Description

Use CreateNew instead of Create to create a data module without using the associated .DFM file to initialize it.

CreateNew bypasses the streaming in of the previously-associated .DFM file; therefore, you must stream in an external .DFM to bind the visual components with their classes. WriteComponentResFile and ReadComponentResFile must bracket CreateNew. The following code sequence

1.	streams-out an external .DFM file

2.	creates a new data module disassociated from any .DFM resource file

3.	streams-in the external .DFM file and binds it to this new data module:

Warning:	Using CreateNew instead of Create can cause unpredictable results because most data modules are written assuming their controls will be created from the .DFM file.

CreateNew calls the inherited constructor, and then informs the global screen object of the existence of the data module.

The first argument, AOwner, is the owner of the data module (usually the application).The second argument, Dummy, defaults to 0 and is not used by this constructor. The system passes 0 by default if this constructor is passed only the first argument, AOwner.


TDataModule::~TDataModule

TDataModule	See also

Destroys the instance of the data module.

__fastcall virtual ~TDataModule(void);

Description

Do not call ~TDataModule directly. Instead call Free to verify that the data module is not already freed before calling ~TDataModule. Before calling the parent object’s destructor, ~TDataModule removes any fixup references, calls its OnDestroy event handler if one is defined, and informs the global screen variable that the data module is going away.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


TDataSet

Hierarchy	Properties	Methods	Events	See also

TDataSet is the virtualized base class for all dataset components that represent data in rows and columns.

Unit

db

Description

TDataSet encapsulates a database-engine independent set of properties, events, and methods for working with data. Many of the properties, events, and methods in TDataSet are abstract or virtual.

Abstract declarations are just that: declarations without implementations. At the TDataSet level they cannot be used or accessed. Developers must use or derive descendants of TDataSet that declare and implement these abstract methods. Virtual methods are declared and implemented in TDataSet, but in many cases, these methods are merely stubs that are reimplemented in descendants such as TClientDataSet, TBDEDataSet, TDBDataSet, TQuery, TStoredProc, and TTable.

For example, both single-tiered and multi-tiered database applications that use distributed datasets access data using TClientDataSet, a direct descendant of TDataSet. Developers who develop their own distributed dataset objects should derive them from TClientDataSet as well.

Similarly, traditional single-tiered and two-tiered database applications access data through the Borland Database Engine (BDE) using TQuery, TStoredProc, or TTable objects. Developers who create custom dataset components that use the BDE directly in a client application derive them from TBDEDataSet, TDBDataSet, TQuery, TStoredProc, or TTable.


TDataSet properties

TDataSet	Alphabetically	Legend

In TDataSet

Active

AutoCalcFields

Bof

Bookmark

CanModify

Constraints

DataSource

DefaultFields

Designer

Eof

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Modified

Name

RecNo

RecordCount

RecordSize

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDataSet properties

TDataSet	By object	Legend

Active

AutoCalcFields

Bof

Bookmark

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Constraints

DataSource

DefaultFields

Designer

DesignInfo

Eof

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Modified

Name

Owner

RecNo

RecordCount

RecordSize

State

Tag

VCLComObject


TDataSet::Active

TDataSet	See also 	Example

Specifies whether or not a dataset is open.

__property bool Active = {read=GetActive, write=SetActive, default=0};

Description

Use Active to determine or set a dataset’s connection to data in a database. When Active is false, the dataset is closed; the dataset cannot read data from or write data to the database. When Active is true, data can be read from and written to the database.

Setting Active to true:

•	Triggers the BeforeOpen event handler if one is defined for the dataset.

•	Sets the dataset state to dsBrowse.

•	Opens a cursor into the dataset.

•	Triggers the After Open event handler if one is defined for the dataset.

If an error occurs during the dataset open, dataset state is set to dsInactive, and the cursor is closed.

An application must set Active to false before changing other properties that affect the status of the database or the controls that display data in an application.

Note:	Calling the Open method sets Active to true; calling the Close method sets Active to false.


TDataSet::AutoCalcFields

TDataSet	See also

Determines when the OnCalcFields event is triggered.

__property bool AutoCalcFields = {read=FAutoCalcFields, write=FAutoCalcFields, default=1};

Description

Set AutoCalcFields to control when the OnCalcFields event is triggered to update calculated fields during dataset processing. A calculated field is one that derives its value from the values of one or more fields in the dataset, sometime with additional processing. When AutoCalcFields is true (the default), OnCalcFields is triggered when:

•	A dataset is opened.

•	A dataset is put into dsEdit state.

•	Focus moves from one visual control to another, or from one column to another is a data-aware grid control and modifications were made to the record.

•	A record is retrieved from a database.

To reduce the frequency with which OnCalcFields is called, set AutoCalcFields to false. When AutoCalcFields is false, OnCalcFields is not called when changes are made to individual fields within a record. If an application permits users to change data, OnCalcFields is frequently triggered. In these cases an application may set AutoCalcFields to false to reduce the frequency with which AutoCalcFields is called.


TDataSet::Bof

TDataSet	See also 	Example

Indicates whether or not a cursor is positioned at the first record in a dataset.

__property bool Bof = {read=FBof, nodefault};

Description

Test Bof (beginning of file) to determine if the cursor is positioned at the first record in a dataset. If Bof is true, the cursor is unequivocally on the first row in the dataset. Bof is true when an application:

•	Opens a dataset.

•	Calls a dataset’s First method.

•	Call a dataset’s Prior method, and the method fails (because the cursor is already on the first row in the dataset).

•	Calls SetRange on an empty range or dataset.

Bof is false in all other cases. An application should assume Bof is false unless one of the conditions above is met and the application tests the property directly.


TDataSet::Bookmark

TDataSet	See also

Specifies the current bookmark in the dataset.

__property System::AnsiString Bookmark = {read=GetBookmarkStr, write=SetBookmarkStr};

Description

Bookmark gets or sets the current bookmark in a dataset. A bookmark provides a convenient way to mark a location in a dataset so that an application can easily return to that location quickly.

An application can read Bookmark to retrieve the bookmark associated with the current record, and it can position the cursor in the dataset by assigning a saved bookmark value to this property.


TDataSet::CanModify

TDataSet	See also

Indicates whether the database underlying a dataset permits write access to data.

__property bool CanModify = {read=GetCanModify, nodefault};

Description

This property is always true for an instance of a TDataSet object. Descendant objects, such as TQuery, TStoredProc, and TTable, redeclare and reimplement this property to perform meaningful tests to determine whether a dataset has write access to data.


TDataSet::Constraints

TDataSet	See also

Specifies record-level constraints that must be met when editing the data.

__property TCheckConstraints* Constraints = {read=FConstraints, write=SetConstraints};

Description

Use Constraints to read or add record-level constraints to the dataset. Record-level constraints usually impose relationships between the fields in a single record. Constraints that limit the value of a single field should be added to the individual field components.


TDataSet::DataSource

TDataSet	See also

Returns NULL for datasets that cannot specify a data source.

__property TDataSource* DataSource = {read=GetDataSource};

Description

DataSource is a property that returns NULL if a dataset cannot specify its own data source.

Descendant dataset objects that support specifying a data source redeclare and implement methods for getting and setting the DataSource property.


TDataSet::DefaultFields

TDataSet	See also

Indicates whether a dataset’s underlying field components are generated dynamically when the dataset is opened.

__property bool DefaultFields = {read=FDefaultFields, nodefault};

Description

Read DefaultFields to determine whether or not a dataset uses dynamically generated field components, or persistent field components. If DefaultFields is true, the dataset uses dynamically allocated field components. If DefaultFields is false, the dataset uses persistent field components.

A dataset always creates dynamic field components based on the structure of its underlying database table or tables when the dataset is opened unless persistent field components are assigned to a dataset at design time using the Fields editor.


TDataSet::Designer

TDataSet	See also

Returns a pointer to the Dataset designer for the dataset.

__property TDataSetDesigner* Designer = {read=FDesigner};

Description

Use Designer to determine whether the dataset is currently being designed and, if so, to access the dataset designer. When a dataset designer, such as the Fields editor, is created for a dataset at design time, it sets the Designer property to itself. When the dataset designer is destroyed, the Designer property is set back to NULL. A Dataset designer enables a developer to specify the fields that belong to a dataset at design time.


TDataSet::Eof

TDataSet	See also 	Example

Indicates whether or not a cursor is positioned at the last record in a dataset.

__property bool Eof = {read=FEof, nodefault};

Description

Test Eof (end-of-file) to determine if the cursor is positioned at the last record in a dataset. If Eof is true, the cursor is unequivocally on the last row in the dataset. Eof is true when an application:

•	Opens an empty dataset.

•	Calls a dataset’s Last method.

•	Call a dataset’s Next method, and the method fails (because the cursor is already on the last row in the dataset).

•	Calls SetRange on an empty range or dataset.

Eof is false in all other cases. An application should assume Eof is false unless one of the conditions above is met and the application tests the property directly.

Tip:	If both Eof and Bof are true, a dataset or range is empty.


TDataSet::FieldCount

TDataSet	See also 	Example

Indicates the number of field components associated with the dataset.

__property int FieldCount = {read=GetFieldCount, nodefault};

Description

Examine FieldCount to determine the number of fields associated with the dataset. For datasets with dynamically-created fields, FieldCount may differ each time a dataset is opened. For datasets with persistent fields, FieldCount should be unchanged each time a dataset is open.


TDataSet::FieldDefs

TDataSet	See also 	Example

Points to the list of field definitions for the dataset.

__property TFieldDefs* FieldDefs = {read=FFieldDefs, write=SetFieldDefs};

Description

FieldDefs points to an internal list of field definitions for a dataset. While an application can examine FieldDefs to explore the field definitions for a dataset, it should not change these definitions unless creating a new table with CreateTable. Otherwise, FieldDefs is primarily intended for internal use by the other properties, events, and methods of TDataSet and its descendants.

To access fields and field values in a dataset, use the Fields and FieldValues properties, and the FieldsByName method.


TDataSet::Fields

TDataSet	See also 	Example

Provides an indexed array of all field components for a dataset.

__property TField* Fields[int Index] = {read=GetField, write=SetField};

Description

Use Fields to access field components by index number. Fields is a zero-based array. If fields are generated dynamically at runtime, the order of field components in Fields corresponds directly to the order of columns in the table or tables underlying a dataset. If a dataset uses persistent fields, then the order of field components corresponds to the ordering of fields specified in the Fields editor at design time.

Accessing fields with the Fields property is useful for applications that:

•	Iterate over some or all fields in a dataset.

•	Work with underlying tables whose internal data structure is unknown at runtime.

If an application knows the data types of individual fields, then it can read or write individual field values through the Fields property. For example, the following statement assigns a field value to the Text property of an edit box:

Edit1->Text = Table1->Fields[0]->AsString;

The next statements assigns a value from an edit box to a field:

Table1->Edit();

Table1->Fields[0]->AsString = Edit1->Text;

Table1->Post();

Note:	The preferred method for retrieving and assigning field values is to use persistent fields or the FieldByName method.


TDataSet::FieldValues

TDataSet	See also 	Example

Provides access to the values for all fields in the current record for the dataset

__property System::Variant FieldValues[System::AnsiString FieldName] = {read=GetFieldValue, write=SetFieldValue};

Description

Use FieldValues to read and write values for fields in a dataset. FieldName is the name of a field to read from or write to.

FieldValues accepts and returns a Variant, so it can handle and convert fields of any type. For example, the following statement writes the value from an edit box into an integer field:

Customers->Edit();

Customers->FieldValues["CustNo"] = Edit1->Text;

Customers->Post();

The next statements reads a string value from a field into an edit box:

Edit1->Text = Customers->FieldValues["Company"];

Note:	Because FieldValues always uses Variants, it may be a somewhat slower method of accessing data, than using a field’s native format (i.e., using a field’s AsXXX property), especially in applications that process large amounts of data.


TDataSet::Filter

TDataSet	See also

Specifies the text of the current filter for a dataset.

__property System::AnsiString Filter = {read=FFilterText, write=SetFilterText};

Description

Use Filter to specify a dataset filter. When filtering is applied to a dataset, only those records that meet a filter’s conditions are available to an application. Filter contains the string that describes the filter condition. For example, the following filter condition displays only those records where the State field is 'CA' or 'MA':

State = 'CA' or State = 'MA'

When a filter is set, Blank records do not appear unless explicitly included in the filter.  For example:

State <> CA or State IS NULL

When a field name contains spaces, you must enclose the field name in brackets. For example:

[Home State] = 'CA' or [Home State] = 'MA'

Filter expressions on remote SQL tables and on client datasets support field comparisons. For example:

Field1 > Field2

Field comparisons are not supported against local tables (Paradox, dBASE, Access, FoxPro).

The FilterOptions property controls case sensitivity and filtering on partial comparisons.

Note:	Applications can set Filter at runtime to change the filtering condition for a dataset at (for example, in response to user input).


TDataSet::Filtered

TDataSet	See also

Specifies whether or not filtering is active for a dataset.

__property bool Filtered = {read=FFiltered, write=SetFiltered, default=0};

Description

Check Filtered to determine whether or not dataset filtering is in effect. If Filtered is true, then filtering is active. Otherwise Filtered is false. To apply filter conditions specified in the Filter property or the OnFilterRecord event handler, set Filtered to true.

Note:	When filtering is enabled, user edits to a record may mean that the record no longer meets a filter’s test condition. The next time an attempt is made to the read the record from the dataset while the filter is in effect the record is not visible. If that happens, the next record that passes the filter condition becomes the current record.


TDataSet::FilterOptions

TDataSet	See also

Specifies whether or not filtering is case insensitive, and whether or not partial comparisons are permitted when filtering records.

__property TFilterOptions FilterOptions = {read=FFilterOptions, write=SetFilterOptions, default=0};

Description

Set FilterOptions to specify whether or not filtering is case insensitive when filtering on string or character fields, and whether or not partial comparisons for matching filter conditions is allowed.

By default, FilterOptions is set to an empty set. For filters based on string fields, set FilterOptions to foCaseInsensitive to catch all variations on a string regardless of capitalization.

When a string in a filter ends with an asterisk (*), it can be used to match partial strings. To disable matching of partial strings and to treat the asterisk as a literal character in string comparisons, set FilterOptions to include foNoPartialCompare.


TDataSet::Found

TDataSet	See also

Indicates whether or not moving to a different record is successful or not.

__property bool Found = {read=GetFound, nodefault};

Description

Check the status of Found to determine if a call to FindFirst, FindLast, FindNext or, FindPrior succeeds. If Found is true, success is indicated. If false, the move to a different record failed.


TDataSet::Modified

TDataSet	See also

Indicates whether the current record is modified.

__property bool Modified = {read=FModified, nodefault};

Description

Check Modified to determine if the current record is modified. If Modified is true, the current record is modified. If false, the current record is not modified.

Note:	In general, an application need not check the status of Modified. Properties, events, and methods of TDataSet and its descendants that modify records generally check this status automatically and take appropriate actions based on its value.


TDataSet::Name

TDataSet	See also

Designates the name of the dataset as referenced by other components.

__property System::AnsiString Name = {read=FName, nodefault};

Description

Use Name to change the name of a dataset to reflect its purpose in the current application. By default, C++Builder assigns sequential names based on the type of the component, such as 'Table1', 'Table2', and so on. When the name of the datset is changed at design time, if any of the field components use the dataset name as a prefix to the field name, these field names are updated as well.


TDataSet::RecNo

TDataSet	See also

Indicates the current record in the dataset.

__property int RecNo = {read=GetRecNo, write=SetRecNo, nodefault};

Description

This function returns -1 in all cases. Ordinarily an application will not access RecNo at the TDataSet level. Instead a redeclared and implemented RecNo property in a descendant object such as TTable is accessed. RecNo provides a fallback property for derived dataset objects that do not reimplement it.


TDataSet::RecordCount

TDataSet	See also

Indicates the total number of records associated with the dataset.

__property int RecordCount = {read=GetRecordCount, nodefault};

Description

This function returns -1 in all cases. Ordinarily an application will not access RecordCount at the TDataSet level. Instead a redeclared and implemented RecordCount property in a descendant object such as TTable is accessed. RecordCount provides a fallback property for derived dataset objects that do not reimplement it.


TDataSet::RecordSize

TDataSet	See also

Indicates the size of a record in the dataset.

__property Word RecordSize = {read=GetRecordSize, nodefault};

Description

RecordSize is an abstract property that is redeclared and implemented in descendant objects derived from TDataSet. For TDataSet, RecordSize is meaningless.


TDataSet::State

TDataSet	See also 	Example

Indicates the current operating mode of the dataset.

enum TDataSetState { dsInactive, dsBrowse, dsEdit, dsInsert, dsSetKey, dsCalcFields, dsFilter, dsNewValue, dsOldValue, dsCurValue };

__property TDataSetState State = {read=FState, nodefault};

Description

Examine State to determine the current operating mode of the dataset. State determines what can be done with data in a dataset, such as editing existing records or inserting new ones. The dataset state constantly changes as an application processes data. The following table lists all possible values for State and describes what they indicate:

Value	Meaning

dsInactive	Dataset is closed, so its data is unavailable.

dsBrowse	Data can be viewed, but not changed. This is the default state of an open dataset.

dsEdit	Current record can be modified.

dsInsert	A new record can be inserted.

dsSetKey	TTable only. Record searching is enabled, or a SetRange operation is under way. A restricted set of data can be viewed, and no data can be edited or inserted.

dsCalcFields	An OnCalcFields event is in progress. Noncalculated fields cannot be edited, and new records cannot be inserted.

dsFilter	An OnFilterRecord event is in progress. A restricted set of data can be viewed. No data can edited or inserted.

dsNewValue	Temporary state used internally to indicate that the TField::NewValue property is being accessed.

dsOldValue	Temporary state used internally to indicate that the TField::OldValue property is being accessed.

dsCurValue	Temporary state used internally to indicate that the TField::CurValue property is being accessed.

Opening a dataset changes State from dsInactive to dsBrowse. An application can call Edit to put a dataset into dsEdit state, or call Insert to put a dataset into dsInsert state. If a dataset is a TTable object, an application can call SetKey or SetRange to put the dataset into dsSetKey state.

Posting or cancelling edits, insertions, or deletions, changes State from its current state to dsBrowse. Closing a dataset changes its state to dsInactive.

Some states, such as dsCalcFields, dsFilter, dsNewValue, dsOldValue, and dsCurValue cannot be seen or set directly by an application. These states are automatically set when OnCalcField and OnFilterRecord events occur, or when an application accesses the TField::XXXValue properties.


TDataSet events

TDataSet	Alphabetically

In TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TDataSet events

TDataSet	By object

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TDataSet::AfterCancel

Example

Occurs after an application completes a request to cancel modifications to the current record.

__property TDataSetNotifyEvent AfterCancel = {read=FAfterCancel, write=FAfterCancel};

Description

Write an AfterCancel event handler to take specific action after an application cancels changes to the current record. AfterCancel is called by the Cancel method after it updates the cursor position, releases the lock on the current record if necessary, and sets the dataset state to dsBrowse. If an application requires additional processing before returning control to a user after a Cancel event, code it in the AfterCancel event.


TDataSet::AfterClose

TDataSet	See also

Occurs after an application closes a dataset.

__property TDataSetNotifyEvent AfterClose = {read=FAfterClose, write=FAfterClose};

Description

Write an AfterClose event handler to take specific action immediately after an application closes a dataset. For example, as a security measure, an application might clear a PASSWORD entry from the Params property of a database component when the dataset is closed.

AfterClose is called after a dataset is closed and the dataset state is set to dsInactive.


TDataSet::AfterDelete

TDataSet	See also 	Example

Occurs after an application deletes a record.

__property TDataSetNotifyEvent AfterDelete = {read=FAfterDelete, write=FAfterDelete};

Description

Write an AfterDelete event handler to take specific action immediately after an application deletes the current record in a dataset. AfterDelete is called by Delete after it deletes the record, sets the dataset state to dsBrowse, and repositions the cursor on the record prior to the one just deleted.


TDataSet::AfterEdit

TDataSet	See also 	Example

Occurs after an application edits a record.

__property TDataSetNotifyEvent AfterEdit = {read=FAfterEdit, write=FAfterEdit};

Description

Write an AfterEdit event handler to take specific action immediately after an application edits a record. AfterEdit is called by Edit after it enables editing of a record, recalculates calculated fields, and calls the data event handler to process a record change.


TDataSet::AfterInsert

TDataSet	See also 	Example

Occurs after an application inserts a new record.

__property TDataSetNotifyEvent AfterInsert = {read=FAfterInsert, write=FAfterInsert};

Description

Write an AfterInsert event handler to take specific action immediately after an application inserts a record. AfterInsert is called by Insert and Append after inserting or appending a new record.


TDataSet::AfterOpen

TDataSet	See also 	Example

Occurs after an application completes opening a dataset and before any data access occurs.

__property TDataSetNotifyEvent AfterOpen = {read=FAfterOpen, write=FAfterOpen};

Description

Write an AfterOpen event handler to take specific action immediately after an application opens the dataset. AfterOpen is called after the cursor for the dataset is opened and the dataset is put into dsBrowse state. For example, an AfterOpen event handler might check the system registry to determine the last record touched in the dataset the previous time the application ran, and position the cursor at that record.


TDataSet::AfterPost

TDataSet	See also 	Example

Occurs after an application writes the current record to the database or cache and before the dataset is returned to browse state.

__property TDataSetNotifyEvent AfterPost = {read=FAfterPost, write=FAfterPost};

Description

Write an AfterPost event handler to take specific action immediately after an application posts a change to the current record. AfterPost is called after a modification, deletion, or insertion is made to a record.


TDataSet::AfterScroll

TDataSet	See also

Occurs after an application scrolls from one record to another.

__property TDataSetNotifyEvent AfterScroll = {read=FAfterScroll, write=FAfterScroll};

Description

Write an AfterScroll event handler to take specific action immediately after an application scrolls to another record as a result of a call to the First, Last, MoveBy, Next, Prior, FindKey, FindFirst, FindNext, FindLast, FindPrior, and Locate methods. AfterScroll is called after all other events triggered by these methods and any other methods that switch from record to record in the dataset.


TDataSet::BeforeCancel

TDataSet	See also

Occurs before an application executes a request to cancel changes to the current record.

__property TDataSetNotifyEvent BeforeCancel = {read=FBeforeCancel, write=FBeforeCancel};

Description

Write a BeforeCancel event to take specific action before an application carries out a request to cancel changes. BeforeCancel is called by the Cancel method before it cancels a dataset operation such as Edit, Insert, or Delete.

An application might use the BeforeCancel event to record a user’s changes in an undo buffer.


TDataSet::BeforeClose

TDataSet	See also

Occurs before an application executes a request to close the dataset.

__property TDataSetNotifyEvent BeforeClose = {read=FBeforeClose, write=FBeforeClose};

Description

Write a BeforeClose event to take specific action before an application closes a dataset. Calling Close or setting the Active property to false results in a call to the BeforeClose event handler.


TDataSet::BeforeDelete

TDataSet	See also

Occurs before an application attempts to delete the current record.

__property TDataSetNotifyEvent BeforeDelete = {read=FBeforeDelete, write=FBeforeDelete};

Description

Write a BeforeDelete event handler to take specific action before an application deletes the current record. BeforeDelete is called by Delete before it actually deletes a record.

Making use of this event an application might, for example, display a dialog box asking for confirmation before deleting the record. On denial of confirmation, the application could abort the deletion by calling the Abort procedure.


TDataSet::BeforeEdit

TDataSet	See also

Occurs before an application enters edit mode for the current record.

__property TDataSetNotifyEvent BeforeEdit = {read=FBeforeEdit, write=FBeforeEdit};

Description

Write a BeforeEdit event handler to take specific action before an application enables editing of the current record. For example, an application might keep a log of database edits, and therefore might record the edit request, time, and user in a BeforeEdit event before entering edit state.


TDataSet::BeforeInsert

TDataSet	See also 	Example

Occurs before an application enters insert mode.

__property TDataSetNotifyEvent BeforeInsert = {read=FBeforeInsert, write=FBeforeInsert};

Description

Write a BeforeInsert event handler to take specific action before an application inserts or appends a new record. BeforeInsert is called by Insert or Append before they set the dataset into dsInsert state.


TDataSet::BeforeOpen

TDataSet	See also

Occurs before an application executes a request to open a dataset.

__property TDataSetNotifyEvent BeforeOpen = {read=FBeforeOpen, write=FBeforeOpen};

Description

Write a BeforeOpen event handler to take specific action before an application opens a dataset for viewing or editing. BeforeOpen is triggered when an application sets the Active property to true for a dataset or an application calls Open.


TDataSet::BeforePost

TDataSet	See also 	Example

Occurs before an application posts changes for the current record to the database or cache.

__property TDataSetNotifyEvent BeforePost = {read=FBeforePost, write=FBeforePost};

Description

Write a BeforePost event handler to take specific action before an application posts dataset changes to the database. BeforePost is triggered when an application calls the Post method. Post checks to make sure all required fields are present, then calls BeforePost before posting the record.

An application might use BeforePost to perform validity checks on data changes before posting them to the database. If it encountered a validity problem, it could call Abort to cancel the Post operation.


TDataSet::BeforeScroll

TDataSet	See also

Occurs before an application scrolls from one record to another.

__property TDataSetNotifyEvent BeforeScroll = {read=FBeforeScroll, write=FBeforeScroll};

Description

Write a BeforeScroll event handler to take specific action immediately after an application scrolls to another record as a result of a call to the First, Last, MoveBy, Next, Prior, FindKey, FindFirst, FindNext, FindLast, FindPrior, and Locate methods. BeforeScroll is called before all other events triggered by these methods and any other methods that switch from record to record in the dataset.


TDataSet::OnCalcFields

TDataSet	See also

Occurs when an application recalculates calculated fields.

__property TDataSetNotifyEvent OnCalcFields = {read=FOnCalcFields, write=FOnCalcFields};

Description

Write an OnCalcFields event handler to take specific action when an application recalculates calculated fields. A calculated field is one that derives its value from the values in one or more fields in the dataset, sometimes with additional processing.

OnCalcFields occurs frequently, so the code it in an OnCalcFields event handler should be brief.

When the AutoCalcFields property is true, OnCalcFields is triggered when:

•	A dataset is opened.

•	A dataset is put into dsEdit state.

•	Focus moves from one visual control to another, or from one column to another is a data-aware grid control and modifications were made to the record.

•	A record is retrieved from a database.

Note:	When the AutoCalcFields property is true, an OnCalcFields event handler should not modify the dataset (or a linked dataset if it is part of a master-detail relationship), because such modifications retrigger the OnCalcField event, leading to recursion.

If an application permits users to change data, OnCalcFields is frequently triggered. To reduce the frequency with which OnCalcFields occurs, set AutoCalcFields to false. When AutoCalcFields is false, OnCalcFields is not called when changes are made to individual fields within a record.


TDataSet::OnDeleteError

TDataSet	See also

Occurs when an application attempts to delete a record and an exception is raised.

__property TDataSetErrorEvent OnDeleteError = {read=FOnDeleteError, write=FOnDeleteError};

Description

Write an OnDeleteError event handler to handle exceptions that occur when an attempt to delete a record fails. E is a pointer to the database error object that contains the exception error message so that an application can display an error message. Action indicates how the handler should respond to the error. The following table summarizes the settings for Action and what they mean:

Value	Meaning

daFail	Aborts the delete operation and displays an error message.

daAbort	Aborts the delete operation without displaying a message.

daRetry	Repeats the delete operation. Correct the error condition inside the error handler before setting Action to daRetry.

When OnDeleteError is first invoked, Action is always set to daFail. If the error handler can correct the error condition that caused the handler to be invoked, set Action to daRetry before exiting the handler. When Action is daRetry, the delete operation is tried again.

If an error condition cannot be corrected, the display of the error message can be suppressed, if desired, by setting Action to daAbort instead of daFail.


TDataSet::OnEditError

TDataSet	See also

Occurs when an application attempts to modify or insert a record and an exception is raised.

__property TDataSetErrorEvent OnEditError = {read=FOnEditError, write=FOnEditError};

Description

Write an OnEditError event handler to handle exceptions that occur when an attempt to edit a record fails. E is a pointer to the database error object that contains the exception error message so that an application can display an error message. Action indicates how the handler should respond to the error. The following table summarizes the settings for Action and what they mean:

Value	Meaning

daFail	Aborts the edit operation and displays an error message.

daAbort	Aborts the edit operation without displaying a message.

daRetry	Repeats the edit operation. Correct the error condition inside the error handler before setting Action to daRetry.

When the OnEditError event handler is first invoked, Action is always set to daFail. If the error handler can correct the error condition that caused the handler to be invoked, set Action to daRetry before exiting the handler. When Action is daRetry, the edit operation is tried again.

If an error condition cannot be corrected, the display of the error message can be suppressed, if desired, by setting Action to daAbort instead of daFail.


TDataSet::OnFilterRecord

TDataSet	See also 	Example

Occurs each time a different record in the dataset becomes the current record and filtering is enabled.

__property TFilterRecordEvent OnFilterRecord = {read=FOnFilterRecord, write=SetOnFilterRecord};

Description

Write an OnFilterRecord event handler to test each record in a dataset for against a test condition that determines whether or not the record is visible to the application. To indicate whether or not a record passes the filter condition, a filter handler must set the Accept parameter to true to include a record, or false to exclude it.

Filtering is enabled if the Filtered property is true. When an application is processing a filter, the State property for the dataset is dsFilter.

Use an OnFilterRecord event handler to filter records using a criterion that can’t be implemented using the Filter property.  For example, using the Filter property, Field comparisons are not supported against local tables (Paradox, dBASE, Access, FoxPro), but an OnFilterRecord event handler can implement any criterion at all.

Note:	Be sure that the interactions between the Filter property and the OnFilterRecord event handler do not result in an empty filter set when they are used simultaneously in an application.


TDataSet::OnNewRecord

TDataSet	See also

Occurs when an application inserts or appends a new dataset record.

__property TDataSetNotifyEvent OnNewRecord = {read=FOnNewRecord, write=FOnNewRecord};

Description

Write an OnNewRecord event handler to take specific actions as an application inserts or appends a new record. OnNewRecord is called as part of the actual insert or append process. An application might use the OnNewRecord event to set initial values for a record or as a way of implementing cascading insertions in related datasets.


TDataSet::OnPostError

TDataSet	See also

Occurs when an application attempts to modify or insert a record and an exception is raised.

__property TDataSetErrorEvent OnPostError = {read=FOnPostError, write=FOnPostError};

Description

Write an OnPostError event handler to handle exceptions that occur when an attempt to edit a record fails. E is a pointer to the database error object that contains the exception error message so that an application can display an error message. Action indicates how the handler should respond to the error. The following table summarizes the settings for Action and what they mean:

Value	Meaning

daFail	Aborts the post operation and displays an error message.

daAbort	Aborts the post operation without displaying a message.

daRetry	Repeats the post operation. Correct the error condition inside the error handler before setting Action to daRetry.

When OnPostError is first invoked, Action is always set to daFail. If the error handler can correct the error condition that caused the handler to be invoked, set Action to daRetry before exiting the handler. When Action is daRetry, the edit operation is tried again.

If an error condition cannot be corrected, the display of the error message can be suppressed, if desired, by setting Action to daAbort instead of daFail.


TDataSet methods

TDataSet	Alphabetically

In TDataSet

~TDataSet

ActiveBuffer

Append

AppendRecord

BookmarkValid

Cancel

CheckBrowseMode

ClearFields

Close

CompareBookmarks

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

Locate

Lookup

MoveBy

Next

Open

Post

Prior

Refresh

Resync

SetFields

TDataSet

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDataSet methods

TDataSet	By object

~TDataSet

ActiveBuffer

Append

AppendRecord

Assign

BookmarkValid

Cancel

CheckBrowseMode

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CompareBookmarks

ControlsDisabled

CursorPosChanged

DefaultHandler

Delete

DestroyComponents

Destroying

DisableControls

Dispatch

Edit

EnableControls

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindLast

FindNext

FindPrior

First

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GotoBookmark

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

Last

Locate

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

Post

Prior

Refresh

RemoveComponent

Resync

SafeCallException

SetFields

TDataSet

Translate

UpdateCursorPos

UpdateRecord


TDataSet::ActiveBuffer

TDataSet	See also

Returns a pointer to the buffer for the current record.

char * __fastcall ActiveBuffer(void);

Description

ActiveBuffer is used internally by many dataset methods to ensure that the active buffer points to the buffer for the current record. If an application uses existing dataset methods, the active buffer is always set correctly, so there is usually no need to call ActiveBuffer directly.

ActiveBuffer is also used by bookmarking methods to index into the current record buffer to retrieve bookmark information.

Applications that provide custom dataset routines may need to call ActiveBuffer to access the buffer data, especially when iterating through a set of records in the dataset. Even in these cases, if custom routines call methods such as Next or Prior, the active buffer is automatically set.


TDataSet::Append

TDataSet	See also 	Example

Adds a new, empty record to the end of the dataset.

void __fastcall Append(void);

Description

Call Append to:

1	Open a new, empty record at the end of the dataset.

2	Set the current record to the new record.

After a call to Append, an application can enable users to enter data in the fields of the record, and can then post those changes to the database using Post (or ApplyUpdates if cached updating is enabled). A newly appended record is posted to the database in one of three ways:

•	For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.

•	For unindexed Paradox and dBASE tables, the record is added to the end of the dataset.

•	For SQL databases, the physical location of the append is implementation-specific. For indexed tables, the index is updated with the new record information.


TDataSet::AppendRecord

TDataSet	See also 	Example

Adds a new, populated record to the end of the dataset and posts it to the database.

void __fastcall AppendRecord(const System::TVarRec * Values, const int Values_Size);

Description

Call AppendRecord to create a new, empty record at the end of the dataset, populate it with the field values in Values, and post the values to the database. A newly appended record is posted to the database in one of three ways:

•	For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.

•	For unindexed Paradox and dBASE tables, the record is added to the end of the dataset.

•	For SQL databases, the physical location of the append is implementation-specific. For indexed tables, the index is updated with the new record information.

The newly appended record becomes the current record.


TDataSet::BookmarkValid

TDataSet	See also

Implements a virtual function that tests the validity of a specified bookmark.

virtual bool __fastcall BookmarkValid(void * Bookmark);

Description

This function returns false in all cases. Ordinarily an application should not call BookmarkValid at the TDataSet level, but instead call a redeclared and implemented BookmarkValid in a descendant object such as TTable. BookmarkValid provides a fallback method for derived dataset objects that do not reimplement BookmarkValid.


TDataSet::Cancel

TDataSet	See also

Cancels modifications to the current record if those changes are not yet posted.

virtual void __fastcall Cancel(void);

Description

Call Cancel to undo modifications made to one or more fields belonging to the current record. As long as those changes are not already posted to the database, Cancel returns the record to its previous state, and sets the dataset state to dsBrowse.

Typically Cancel is used to back out of changes in response to user request, or in field validation routines that back out illegal field values. The TDBNavigator object contains a Cancel button that triggers a call to Cancel.


TDataSet::CheckBrowseMode

TDataSet	See also

Automatically posts or cancels data changes when an application calls a method that changes which record in a dataset is the current record.

void __fastcall CheckBrowseMode(void);

Description

CheckBrowseMode is used internally by many dataset methods to ensure that modifications to the current record are posted to the database when a dataset’s state is dsEdit, dsInsert, or dsSetKey state and a method is called that switches to a different record.

If State is dsEdit or dsInsert, CheckBrowseMode calls UpdateRecord, and then, if the Modified property for the dataset is true, CheckBrowseMode calls Post. If Modified is false, CheckBrowseMode calls Cancel.

If State is dsSetKey, CheckBrowseMode calls Post.

If State is dsInactive, CheckBrowseMode raises an exception.

If an application uses existing dataset methods, CheckBrowseMode is always called when necessary, so there is usually no need to call CheckBrowseMode directly.

Applications that provide custom dataset routines may need to call CheckBrowseMode inside those routines to guarantee that changes are posted to the database when switching to a different record.


TDataSet::ClearFields

TDataSet	See also

Clears the contents of all fields for the current record.

void __fastcall ClearFields(void);

Description

Call ClearFields to erase the current contents of all fields for the current record. If the dataset is not in either dsInsert or dsEdit state, ClearFields raises an exception.

If a SetKey operation is not under way, ClearFields recalculates all calculated fields, and generates an OnDataChange event on the data source component associated with the dataset.


TDataSet::Close

TDataSet	See also

Closes a dataset.

void __fastcall Close(void);

Description

Call Close to set the Active property of a dataset to false. When Active is false, the dataset is closed; the dataset cannot read data from or write data to the database.

An application must set Active to false before changing other properties that affect the status of the database or the controls that display data in an application. For example, to change the DataSource property for a dataset, Active must first be set to false, ensuring that the dataset is closed. Setting Active to false puts the dataset into dsInactive state and closes the BDE cursor.


TDataSet::CompareBookmarks

TDataSet	See also	Example

Implements a virtual function to compare two bookmarks.

virtual int __fastcall CompareBookmarks(void * Bookmark1, void * Bookmark2);

Description

This function returns 0 in all cases. Ordinarily an application should not call CompareBookmarks at the TDataSet level, but instead call a redeclared and implemented CompareBookmarks in a descendant object such as TTable. CompareBookmarks provides a fallback method for derived dataset objects that do not reimplement CompareBookmarks.


TDataSet::ControlsDisabled

TDataSet	See also

Determines if the updating of data display in data-aware controls is currently disabled for the dataset.

bool __fastcall ControlsDisabled(void);

Description

Call ControlsDisabled to determine if the updating of data display in data-aware controls is currently disabled. If ControlsDisabled is true, controls are currently disabled. ControlsDisabled is true as long as the reference count that keeps track of disabling for the dataset is greater than zero. This count is incremented every time the DisableControls procedure is called. Applications should call DisableControls to improve performance and prevent constant display updating during an automated iteration through a large number of records in the dataset.

In complex applications, when controls may be disabled multiple times by different processes, you can use ControlsDisabled as a check in a procedure to reenable controls should each call to DisableControls not be paired with a subsequent call to EnableControls. For example,

void __fastcall TForm1::ReEnableControls(TDataSet *DataSet)

{

  while (DataSet->ControlsDisabled())

    DataSet->EnableControls();

}


TDataSet::TDataSet

TDataSet	See also

Creates an instance of a TDataSet component.

__fastcall virtual TDataSet(Classes::TComponent* AOwner);

Description

Call TDataSet to instantiate a dataset component at runtime. Ordinarily applications instantiate dataset descendants, such as TTable, TQuery, or TStoredProc, rather than TDataSet. These instantiated objects are handled automatically.

On the other hand, applications that create specialized dataset components, such as custom components which bypass the Borland Database Engine (BDE), may need to instantiate a TDataSet component by calling TDataSet. TDataSet:

•	Creates empty field definitions for the dataset.

•	Creates an empty list of fields for the dataset.

•	Creates an empty list of data sources for the dataset.

•	Set the AutoCalcFields property to true.

•	Clears the field buffers for the dataset.


TDataSet::CursorPosChanged

TDataSet	See also

Sets the cursor position in the dataset to -1.

void __fastcall CursorPosChanged(void);

Description

CurPosChanged is an internal method that invalidates the variable that tracks the physical cursor position relative to the logical cursor position. CurPosChanged is called by the Locate and Lookup methods prior to searching for a requested record. These methods, if successful, reposition the cursor at the first matching record found.


TDataSet::Delete

TDataSet	See also

Deletes the current record and positions the cursor on the next record.

void __fastcall Delete(void);

Description

Call Delete to remove the current record from the database. If the dataset is inactive, Delete raises an exception. Otherwise Delete:

•	Verifies that the dataset is not empty (and raises an exception if it is).

•	Calls CheckBrowseMode to post any pending changes to a prior record if necessary.

•	Triggers the BeforeDelete event handler.

•	Deletes the record.

•	Frees the buffers allocated for the record.

•	Puts the dataset into dsBrowse mode.

•	Resynchronizes the dataset to position the cursor on the next undeleted record.

•	Calls the AfterDelete event handler.


TDataSet::~TDataSet

TDataSet	See also

Destroys the instance of a dataset component.

__fastcall virtual ~TDataSet(void);

Description

Do not call ~TDataSet directly in an application. Usually destruction of datasets is handled automatically by C++Builder. If an application creates its own instances of a dataset, however, the application should call Free, which verifies that the dataset component is not already freed before calling ~TDataSet.

~TDataSet performs the following tasks:

•	Closes the dataset.

•	Frees the Dataset Designer for the dataset, if one exists.

•	Disassociated the dataset from its data source components and frees the memory allocated for them.

•	Destroys the fields associated with the dataset and frees the memory allocated to them.

•	Frees the memory allocated for field definitions.

•	Calls the parent object’s destructor.


TDataSet::DisableControls

TDataSet	See also 	Example

Disables data display in data-aware controls associated with the dataset through a data source component.

void __fastcall DisableControls(void);

Description

Call DisableControls to prevent data display in data-aware controls prior to iterating through a large number of records in the dataset. Disabling controls prevents flicker in controls during rapid iteration through the dataset and its speeds performance because data does not need to be written to the display.

If controls are not already disabled, DisableControls records the current state of the dataset, sets the enabling event for the dataset to deDataSetChange, and increments the dataset’s disabled count variable. Otherwise, DisableControls just increments the disabled count variable.

The enabling event and disabled count variable are used internally by other methods and objects to determine whether or not to display data in data-aware controls. When the disable count variable is greater than zero, data is not displayed.

Note:	DisableControls can safely be called when controls are already disabled. In complex applications there may be separate operations that are sometimes nested, both of which need to disable controls.


TDataSet::Edit

TDataSet	See also 	Example

Enables editing of data in the dataset.

void __fastcall Edit(void);

Description

Call Edit to permit editing of the current record in a dataset. Edit determines the current state of the dataset. If the dataset is empty, Edit calls Insert. Otherwise Edit:

•	Calls CheckBrowseMode to post any pending changes to a prior record if necessary.

•	Triggers the BeforeEdit event handler.

•	Retrieves the record.

•	Puts the dataset into dsEdit state, enabling the application or user to modify fields in the record.

•	Triggers the record change event.

•	Triggers the AfterEdit event handler.


TDataSet::EnableControls

TDataSet	See also 	Example

Enables data display in data-aware controls associated with the dataset through a data source component.

void __fastcall EnableControls(void);

Description

Call EnableControls to permit data display in data-aware controls after a prior call to DisableControls. EnableControls decrements the disabled count variable for the dataset if it is not already zero. If the disable count variable is zero, EnableControls updates the current state of the dataset, if necessary, and then call an event handler for renabling data display.


TDataSet::FieldByName

TDataSet	See also 	Example

Finds a field based on a specified field name.

TField* __fastcall FieldByName(const System::AnsiString FieldName);

Description

Call FieldByName to retrieve field information for a field when only the field’s name is known. FieldName is the name of an existing field. FieldByName returns the TField component for the specified field.

An application can access specific properties and methods of the field directly. For example, the following statement determines if a specified field is a calculated field or not:

if (Customers->FieldByName("FullName")->Calculated)

    ShowMessage("This is a calculated field");

FieldByName is especially useful at design time for developers who are creating database applications, but who do not have access to the underlying table and therefore cannot use persistent field components.

Note:	To retrieve or set the value for a specific field, call the default dataset method FieldValues instead of FieldByName.


TDataSet::FindField

TDataSet	See also 	Example

Searches for a specified field object in the dataset.

TField* __fastcall FindField(const System::AnsiString FieldName);

Description

Call FindField to determine if a specified field component exists in a dataset. FieldName is the name of the field for which to search. If FindField finds a field with a matching name, it returns the TField component for the specified field. Otherwise it returns NULL.

FindField is a useful function to call prior to calling other dataset methods, such as FieldByName, that require a valid field name as a parameter.


TDataSet::FindFirst

TDataSet	See also

Implements a virtual method for positioning the cursor on the first record in a filtered dataset.

bool __fastcall FindFirst(void);

Description

This function returns false, indicating that the cursor was not successfully repositioned. Ordinarily an application should not call FindFirst at the TDataSet level, but instead call a redeclared and implemented FindFirst in a descendant object such as TTable. FindFirst provides a fallback method for derived dataset objects that do not reimplement FindFirst.


TDataSet::FindLast

TDataSet	See also

Implements a virtual method for positioning the cursor on the last record in a filtered dataset.

bool __fastcall FindLast(void);

Description

This function returns false, indicating that the cursor was not successfully repositioned. Ordinarily an application should not call FindLast at the TDataSet level, but instead call a redeclared and implemented FindLast in a descendant object such as TTable. FindLast provides a fallback method for derived dataset objects that do not reimplement FindLast.


TDataSet::FindNext

TDataSet	See also

Implements a virtual method for positioning the cursor on the next record in a filtered dataset.

bool __fastcall FindNext(void);

Description

This function returns false, indicating that the cursor was not successfully repositioned. Ordinarily an application should not call FindNext at the TDataSet level, but instead call a redeclared and implemented FindNext in a descendant object such as TTable. FindNext provides a fallback method for derived dataset objects that do not reimplement FindNext.


TDataSet::FindPrior

TDataSet	See also 	Example

Implements a virtual method for positioning the cursor on the previous record in a filtered dataset.

bool __fastcall FindPrior(void);

Description

This function returns false, indicating that the cursor was not successfully repositioned. Ordinarily an application should not call FindPrior at the TDataSet level, but instead call a redeclared and implemented FindPrior in a descendant object such as TTable. FindPrior provides a fallback method for derived dataset objects that do not reimplement FindPrior.


TDataSet::First

TDataSet	See also 	Example

Implements a generic method to position the cursor on the first record in the dataset.

void __fastcall First(void);

Description

Do not call First at the TDataSet level. In TDataSet descendants, call First to position the cursor on the first record in the dataset and make it the current record. First posts any changes to the current record and:

•	Clears the record buffers.

•	Sets the cursor to the beginning of the dataset file.

•	Calls a virtual, abstract method to fetch the first record, position the cursor on it, and make it the current record. For TDataSet this method is only declared, not implemented.

•	Fetches any additional records required for display, such as those needed to fill out a grid control. In TDataSet this method calls another virtual, abstract method that is only declared, not implemented.

•	Sets the Bof property to true.

•	Triggers an event handler for dataset change events.


TDataSet::FreeBookmark

TDataSet	See also 	Example

Frees the resources allocated for a specified bookmark.

virtual void __fastcall FreeBookmark(void * Bookmark);

Description

Call FreeBookmark to:

•	Free an existing bookmark before reassigning it.

•	Release the memory allocated for a specified bookmark when the bookmark is no longer needed.


TDataSet::GetBookmark

TDataSet	See also 	Example

Allocates a bookmark for the current cursor position in the dataset.

virtual void * __fastcall GetBookmark(void);

Description

Call GetBookmark to establish a bookmark for the current record in the dataset. Establishing a bookmark for a record enables an application to return to that record in the dataset at any time while the bookmark exists.

GetBookmark requires that a variable of type TBookmark already be declared in an application. Use GetBookmark to assign the variable a value that can be referenced by subsequent calls to GotoBookmark and FreeBookmark.

Note:	Applications that create bookmarks with GetBookmark should subsequently release the system resource allocated to them by calling FreeBookmark when the bookmarks are no longer needed.


TDataSet::GetCurrentRecord

TDataSet	See also

Implements a virtual function to retrieve the current record in a buffer.

virtual bool __fastcall GetCurrentRecord(char * Buffer);

Description

This function always returns false, indicating failure. Most applications should not call GetCurrentRecord at the TDataSet level. Instead they should call a redeclared and reimplemented GetCurrentRecord method in a descendant object, such as TTable. GetCurrentRecord provides a fallback function for derived objects that do not redeclare and implement this function.


TDataSet::GetFieldList

TDataSet	See also

Retrieves a specified set of field objects into a list.

void __fastcall GetFieldList(Classes::TList* List, const System::AnsiString FieldNames);

Description

Call GetFieldList to copy a specified set of field objects into a list object created and maintained by the application.

List is the TList object into which to copy the field objects. FieldNames is a string containing the name of the fields to copy. Each field name in the string must be separated from other field names with a semicolon. GetFieldList builds a list that contains only the field objects for which it finds a matching name in the dataset’s list of field objects.

Note:	Applications do not normally have to call GetFieldList to copy field objects. Field objects are directly accessible through the dataset itself. In some cases, however, it can be useful to work with a copy of a field object or its data instead of working on the actual object in the dataset. In these cases, GetFieldList is useful.


TDataSet::GetFieldNames

TDataSet	See also

Retrieves a list of names for all fields in a dataset.

void __fastcall GetFieldNames(Classes::TStrings* List);

Description

Call GetFieldNames to get a list of names for all fields in a dataset. List is a TStrings object created and maintained by the application.

Retrieving a list of field names is especially useful for applications that work with datasets whose field objects are created dynamically at runtime. By retrieving a list of field names, the application can be restricted to working only with fields that exist at runtime.


TDataSet::GotoBookmark

TDataSet	See also 	Example

Implements a virtual method to position the cursor on the record pointed to by a specified bookmark.

void __fastcall GotoBookmark(void * Bookmark);

Description

Do not call GotoBookmark at the TDataSet level. GotoBookmark calls a virtual, abstract internal method that is not implemented by TDataSet. Instead, descendants of TDataSet redeclare and implement the GotoBookmark method, and applications should call the descendants’ methods instead.


TDataSet::Insert

TDataSet	See also 	Example

Inserts a new, empty record in the dataset.

HIDESBASE void __fastcall Insert(void);

Description

Call Insert to:

1	Open a new, empty record in the dataset.

2	Set the current record to the new record.

After a call to Insert, an application can enable users to enter data in the fields of the record, and can then post those changes to the database using Post (or ApplyUpdates if cached updating is enabled). A newly inserted record is posted to the database in one of three ways:

•	For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.

•	For unindexed Paradox and dBASE tables, the record is inserted into the dataset at the current cursor position.

•	For SQL databases, the physical location of the append is implementation-specific. For indexed tables, the index is updated with the new record information.


TDataSet::InsertRecord

TDataSet	See also 	Example

Inserts a new, populated record to the dataset and posts it to the database.

void __fastcall InsertRecord(const System::TVarRec * Values, const int Values_Size);

Description

Call InsertRecord to create a new, empty record at in the dataset, populate it with the field values in Values, and post the values to the database. A newly inserted record is posted to the database in one of three ways:

•	For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.

•	For unindexed Paradox and dBASE tables, the record is inserted into the dataset at the current cursor position.

•	For SQL databases, the physical location of the insert is implementation-specific. For indexed tables, the index is updated with the new record information.

The newly inserted record becomes the current record.


TDataSet::IsEmpty

TDataSet	See also

Determines if a dataset contains no records.

bool __fastcall IsEmpty(void);

Description

Call IsEmpty to determine if a dataset has records. IsEmpty returns true if the dataset does not contain any records. Otherwise it returns false.


TDataSet::IsLinkedTo

TDataSet	See also

Checks that a dataset is linked to a specified data source.

bool __fastcall IsLinkedTo(TDataSource* DataSource);

Description

Call IsLinkedTo to verify that a dataset is linked to a specific data source. DataSource is the name of the data source against which to test.

Note:	IsLinkedTo is mainly provided for developers deriving custom components based on TDataSet. It is not intended or needed for general data access.

If the dataset already uses the specified data source, IsLinkedTo returns true. If the dataset does not use the specified data source, and the data source does not already have a dataset of its own, IsLinkedTo returns false.


TDataSet::Last

TDataSet	See also	Example

Implements a generic method to position the cursor on the last record in the dataset.

void __fastcall Last(void);

Description

Do not call Last at the TDataSet level. In TDataSet descendants, call Last to position the cursor on the last record in the dataset and make it the current record. Last posts any changes to the current record and:

•	Clears the record buffers.

•	Sets the cursor to the end of the dataset file.

•	Calls a virtual, abstract method to fetch the last record, position the cursor on it, and make it the current record. For TDataSet this method is only declared, not implemented.

•	Fetches any additional records required for display, such as those needed to fill out a grid control. In TDataSet this method calls another virtual, abstract method that is only declared, not implemented.

•	Sets the Eof property to true.

•	Triggers an event handler for dataset change events.


TDataSet::Locate

TDataSet	See also	Example

Implements a virtual method for searching a dataset for a specified record and makes that record the current record.

virtual bool __fastcall Locate(const System::AnsiString KeyFields, const System::Variant &KeyValues, TLocateOptions Options);

Description

This function returns false, indicating that a matching record was not found and the cursor is not repositioned. Ordinarily an application does not call Locate at the TDataSet level, but instead calls a redeclared and implemented FindLast in a descendant object such as TTable. Locate provides a fallback method for derived dataset objects that do not reimplement Locate.


TDataSet::Lookup

TDataSet	See also

Implements a virtual method to retrieve field values from a record that matches specified search values.

virtual System::Variant __fastcall Lookup(const System::AnsiString KeyFields, const System::Variant &KeyValues, const System::AnsiString ResultFields);

Description

This function returns false, indicating that a matching field was not found. Ordinarily an application does not call Lookup at the TDataSet level, but instead call a redeclared and implemented Lookup in a descendant object such as TTable. Lookup provides a fallback method for derived dataset objects that do not reimplement Lookup.


TDataSet::MoveBy

TDataSet	See also	Example

Positions the cursor on a record relative to the current record in the dataset.

int __fastcall MoveBy(int Distance);

Description

Call MoveBy to position the cursor on a record relative to the current record in the dataset. Distance indicates the number of records to move. A positive value for Distance indicates forward progress through the dataset, while a negative value indicates backward progress. For example, the following statement moves backward through the dataset by 10 records:

MoveBy posts any changes to the current record and:

•	Sets the Bof and Eof properties to false.

•	If Distance is positive, repeatedly fetches subsequent records, if possible, decrementing Distance until it is zero, positions the cursor on the last record fetched, and makes it the current record. If an attempt is made to move past the end of the file, MoveBy sets Eof to true.

•	If Distance is negative, repeatedly fetches previous records, if possible, incrementing Distance until it is zero, positions the cursor on the last record fetched, and makes it the current record. If an attempt is made to move past the start of the file, MoveBy sets Bof to true.

•	Triggers an event handler for dataset scrolling events.

•	Returns the actual number of records moved. In most cases, Result is the absolute value of Distance, but if MoveBy encounters the beginning-of-file or end-of-file before moving Distance records, Result will be less than the absolute value of Distance.


TDataSet::Next

TDataSet	See also 	Example

Implements a generic method to position the cursor on the next record in the dataset.

void __fastcall Next(void);

Description

Do not call Next at the TDataSet level. In TDataSet descendants, call Next to position the cursor on the next record in the dataset and make it the current record. Next posts any changes to the current record and:

•	Sets the Bof and Eof properties to false.

•	Calls a virtual, abstract method to move to the next record, position the cursor on it, and make it the current record. For TDataSet this method is only declared, not implemented.

•	Fetches any additional records required for display, such as those needed to fill out a grid control. In TDataSet this method calls another virtual, abstract method that is only declared, not implemented.

•	Sets the Eof properties to true if the cursor was already on the last record in the dataset.

•	Triggers an event handler for dataset scrolling events.


TDataSet::Open

TDataSet	See also

Opens the dataset.

void __fastcall Open(void);

Description

Call Open to set the Active property for the dataset to true. When Active is true, data can be read from and written to the database.

Setting Active to true:

•	Triggers the BeforeOpen event handler if one is defined for the dataset.

•	Sets the dataset state to dsBrowse.

•	Opens a Borland Database Engine (BDE) cursor into the dataset, if appropriate (only applies to TBDEDataSet and its descendants, TQuery, TStoredProc, and TTable).

•	Triggers the After Open event handler if one is defined for the dataset.

If an error occurs during the dataset open, dataset state is set to dsInactive, and the cursor is closed.


TDataSet::Post

TDataSet	See also 	Example

Implements a virtual method to write a modified record to the database.

virtual void __fastcall Post(void);

Description

TDataSet implements a virtual method to write a modified record to the database. Dataset methods that change the dataset state, such as Edit, Insert, or Append, or that move from one record to another, such as First, Last, Next, and Prior automatically call Post.

All descendants of TDataSet redeclare and implement Post to write a record to the database.


TDataSet::Prior

TDataSet	See also

Implements a generic method to position the cursor on the previous record in the dataset.

void __fastcall Prior(void);

Description

Do not call Prior at the TDataSet level. In TDataSet descendants, call Prior to position the cursor on the previous record in the dataset and make it the current record. Prior posts any changes to the current record and:

•	Sets the Bof and Eof properties to false.

•	Calls a virtual, abstract method to move to the previous record, position the cursor on it, and make it the current record. For TDataSet this method is only declared, not implemented.

•	Fetches any additional records required for display, such as those needed to fill out a grid control. In TDataSet this method calls another virtual, abstract method that is only declared, not implemented.

•	Sets the Bof properties to true if the cursor was already on the first record in the dataset.

•	Triggers an event handler for dataset scrolling events.


TDataSet::Refresh

TDataSet	See also

Implements a generic method to refetch data from the database to update a dataset’s view of data.

void __fastcall Refresh(void);

Description

Do not call Refresh for a TDataSet object. Instead call the redeclared and reimplemented Refresh method for a TDataSet descendant. Refresh ensures that an application has the latest data from a database. For example, when an application turns off filtering for a dataset, it should immediately call Refresh to display all records in the dataset, not just those that used to meet the filter condition.


TDataSet::Resync

TDataSet	See also

Refetches the current record and the records that precede and follow it.

virtual void __fastcall Resync(TResyncMode Mode);

Description

Resync is an internal routine used by other dataset methods to resynchronize the C++Builder dataset with underlying physical data when making calls that may change the cursor position. Applications should use the Refresh method instead of calling Resync.

Mode indicates optional processing that Resync should handle.

If Mode contains rmExact, Resync raises an exeception if Resync is called when the cursor is not positioned on a valid record.

If Mode contains rmCenter, Resync positions the current record in the center of all buffered records.

Regardless of Mode, Resync also activates the buffers for the current record, retrieves prior and subsequent records for display purposes, and triggers a dataset change event.


TDataSet::SetFields

TDataSet	See also

Sets the values for all fields in a record

void __fastcall SetFields(const System::TVarRec * Values, const int Values_Size);

Description

Call SetFields to set values for some or all fields in the current record at the same time.

Values contains the values to insert into each field. Values are assigned to the record based on the order of columns in the table or tables underlying the dataset. These values can be literals, variables, NULL, or NULL. If Values contains fewer values than there are fields in the record, all records for which values are not provided are assigned a NULL value. A NULL value overwrites any existing value in such fields.

Before calling SetFields, call Edit to put the dataset into dsEdit state. After calling SetFields, call Post to write the changes to the database.

Note:	To set values for some fields while retaining existing values for others, pass NULL for each field that should not change.


TDataSet::Translate

TDataSet

Implements a virtual procedure to copy a data string from a source to a destination, optionally performing character translation during the copy.

virtual void __fastcall Translate(char * Src, char * Dest, bool ToOem);

Description

This function copies a source string to a destination string, and ignores the value passed in ToOem. Ordinarily an application should not call Translate at the TDataSet level, but instead call a redeclared and implemented Translate in a descendant object such as TTable or a developer-derived object. Translate provides a fallback method for derived dataset objects that do not reimplement Translate.


TDataSet::UpdateCursorPos

TDataSet	See also

Positions the cursor on the current record.

void __fastcall UpdateCursorPos(void);

Description

UpdateCursorPos is an internal routine used by many dataset methods to ensure that the physical cursor is positioned on the current record. Normally an application should not need to call UpdateCursorPos. Typically UpdateCursorPos is called to ensure that the physical cursor position matches the logical cursor position.


TDataSet::UpdateRecord

TDataSet	See also

Triggers a data event for a record update.

void __fastcall UpdateRecord(void);

Description

UpdateRecord is an internal routine used by some dataset methods to trigger an OnUpdateRecord event if cached updates are enabled. Applications should not need to call UpdateRecord directly unless they provide custom dataset methods that bypass dataset methods.


Scope

Protected

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent


 TDataSource

Hierarchy	Properties	Methods	Events	See also

TDataSource provides an interface between a dataset component and data-aware controls on a form.

Unit

db

Description

Use TDataSource to provide a conduit between a dataset and data-aware controls on a form that enable display, navigation, and editing of the data underlying the dataset.

All datasets must be associated with a data source component if their data is to be displayed and manipulated in data-aware controls. Similarly, each data-aware control needs to be associated with a data source component in order for the control to receive and manipulate data.

Data source components also link datasets in master-detail relationships.


TDataSource properties

TDataSource	Alphabetically	Legend

In TDataSource

AutoEdit

DataSet

Enabled

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDataSource properties

TDataSource	By object	Legend

AutoEdit

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataSet

DesignInfo

Enabled

Name

Owner

State

Tag

VCLComObject


TDataSource::AutoEdit

TDataSource	See also

Determines if a data source component automatically calls a dataset’s Edit method when a data-aware control associated with the data source receives focus.

__property bool AutoEdit = {read=FAutoEdit, write=FAutoEdit, default=1};

Description

AutoEdit is true by default. If AutoEdit is true, then when a user attempts to modify the data displayed by the control the underlying dataset’s Edit method is called.

Set AutoEdit to false to protect data from unintentional modification. Even if AutoEdit is false, an application can call a dataset’s Edit method directly to permit data modification.


TDataSource::DataSet

TDataSource	See also

Specifies the dataset for which the data source component serves as a conduit to data-aware controls.

__property TDataSet* DataSet = {read=FDataSet, write=SetDataSet};

Description

Set DataSet to the name of an existing dataset component either at design time, or at runtime. By changing the value of DataSet at runtime an application can effectively use the same data-aware controls to display and edit data in different datasets.

Note:	To link a dataset that resides in a data module to a form at design-time, choose File | Use unit.


TDataSource::Enabled

TDataSource	See also

Determines if the data-aware controls associated with the data source component display data.

__property bool Enabled = {read=FEnabled, write=SetEnabled, default=1};

Description

Use Enabled to control whether or not data-aware controls connected to a data source display data. If Enabled is true (the default), data are displayed. If Enabled is false, all controls associated with the data source are blank.

Note:	While an application can set Enabled to false to blank out data-aware controls during processing of multiple records, a better choice is to use the TDataSet EnableControls and DisableControls methods. Using these methods prevents the controls from blanking out during processing.


TDataSource::State

TDataSource	See also	Example

Reads the current state of the dataset component associated with a data source component.

__property TDataSetState State = {read=FState, nodefault};

Description

Examine State to determine the current state of the dataset associated with a data source component. The state of a dataset indicates the action, if any, taking place against the dataset. The following table summarizes possible values for State:

State	Meaning

dsInactive	Dataset is closed, DataSet property is unassigned, or Enabled property is false.

dsBrowse	Dataset is open for viewing. This is the default state for a dataset.

dsEdit	Dataset is open. The current record can be modified.

dsInsert	Dataset is open. A new record is being inserted.

dsSetKey	Dataset is open. Searching for records based on indexed fields is enabled, or a SetRange operation is in progress. In either case a restricted set of data can be viewed. No data can be modified.

dsCalcFields	Dataset is open, and an OnCalcFields event is in progress. Fields that are not calculated cannot be modified.

dsFilter	Dataset is open, and a filter operation is in progress. A restricted set of data can be viewed. No data can be modified.

These values correspond to the values for a dataset’s State property and are identical to them except that when Enabled is false or DataSet is unassigned, State is dsInactive regardless of the actual state of the dataset.


TDataSource events

TDataSource	Alphabetically	Legend

In TDataSource

OnDataChange

OnStateChange

OnUpdateData


TDataSource events

TDataSource	By object	Legend

OnDataChange

OnStateChange

OnUpdateData


TDataSource::OnDataChange

TDataSource	See also 	Example

Occurs when the current record has been edited and the application moves from one field or record to another in a dataset associated with the data source component.

__property TDataChangeEvent OnDataChange = {read=FOnDataChange, write=FOnDataChange};

Description

Write an OnDataChange event handler to take specific actions when a field in the current record has been edited and an application moves from one field or record to another in a dataset associated with a data source component. For example, methods that can trigger this event include the Next or Prior methods for the dataset.

Data-aware controls notify a data source of a data change because of:

•	Scrolling to a new record.

•	Modifications to a field’s data.

The Field parameter is NULL if more than one of the fields changed simultaneously, such as when moving from one record to another. Otherwise, Field indicates the edited field.

OnDataChange is especially useful in applications that must synchronize data display in controls that are not data aware.


TDataSource::OnStateChange

TDataSource	See also

Occurs when the state of a data source component’s dataset changes.

__property Classes::TNotifyEvent OnStateChange = {read=FOnStateChange, write=FOnStateChange};

Description

Write an OnStateChange event handler to take specific actions when the State property changes for a dataset associated with a data source component.

During the course of a normal connection to a database, a dataset’s state changes frequently. For example, each time a user starts editing a field in a data-aware control the dataset’s State property is changed from dsBrowse to dsEdit if the State is not already dsEdit. An OnStateChange event handler might respond to changes in state by taking actions such as disabling or enabling menu items or buttons.


TDataSource::OnUpdateData

TDataSource	See also

Occurs when the data in the current record is about to be updated.

__property Classes::TNotifyEvent OnUpdateData = {read=FOnUpdateData, write=FOnUpdateData};

Description

Write an OnUpdateData event handler to take specific actions prior to posting data changes to the database. If an application posts changes to the database and an OnUpdateData event handler exists, the handler is called before the dataset’s Post method is executed. An OnUpdateData event handler might be useful for performing additional data processing or validation before posting.


TDataSource methods

TDataSource	Alphabetically

In TDataSource

~TDataSource

Edit

IsLinkedTo

TDataSource

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDataSource methods

TDataSource	By object

~TDataSource

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Edit

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsLinkedTo

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TDataSource


TDataSource::TDataSource

TDataSource	See also

Creates an instance of a TDataSource component.

__fastcall virtual TDataSource(Classes::TComponent* AOwner);

Description

Call TDataSource to instantiate a TDataSource component at runtime. For a data source component added to a data module at design time C++Builder automatically inserts a call to TDataSource.

TDataSource instantiates a data link list, and sets the Enabled and AutoEdit properties of the component to true.


TDataSource::~TDataSource

TDataSource	See also

Destroys the instance of a data source component.

__fastcall virtual ~TDataSource(void);

Description

Do not call ~ TDataSource directly. Instead, use the delete keyword on the object, which causes ~ TDataSource to be invoked automatically.

~TDataSource sets OnStateChange to NULL, sets the dataset for the component to NULL, and frees the data link list before calling the parent object’s destructor for the component.


TDataSource::Edit

TDataSource	See also

Determines whether or not to call the Edit method for a dataset associated with a data source component.

void __fastcall Edit(void);

Description

Call Edit to enable a data source component to control a user’s ability to edit a dataset associated with the data source. Edit checks that the AutoEdit property of the data source is true and that its State property is dsBrowse before calling the dataset’s Edit method. Checking these properties before calling the dataset’s Edit method ensures that the dataset is in a state that supports editing, and that the data source allows editing as well.


TDataSource::IsLinkedTo

TDataSource	See also

Checks that a data source is linked to a specified dataset.

bool __fastcall IsLinkedTo(TDataSet* DataSet);

Description

Call IsLinkedTo to verify that a data source is linked to a specific dataset. DataSet is the name of the dataset to which the data source should be linked.

If the data source already uses the specified dataset, IsLinkedTo returns true. If the data source does not use the specified dataset, but the dataset exists, then IsLinkedTo sets the DataSet property of the data source component to the one specified in the DataSet parameter, and returns true.

If the data source does not use the specified dataset, and the dataset does not already have a data source of its own, IsLinkedTo returns false.

Note:	IsLinkedTo is a low-level method mainly of interest to component developers who need to detect circular data references. Otherwise IsLinkedTo should not be called directly.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


TCustomDataStore

Hierarchy	Properties	Methods	Events	See also

TCustomDataStore is the base class for components that analyze and maintain crosstabulated data.

Unit

mxstore

Description

Use TCustomDataStore as a base class when defining classes that fetch data from appropriately structured datasets and analyze it into a multidimensional array of summary values. Each dimension corresponds to a field in the dataset over which information is summarized. TCustomDataStore maintains a cached projection of this array over a set of active dimensions. The cache allows TCustomDataStore to quickly provide a projection of any subset of the active dimensions.

TCustomDataStore introduces properties and methods that describe the dimensions of the crosstabulated data array and the summary values that are computed over those dimensions.

Do not create instances of TCustomDataStore. To make the crosstabulated data from a TCustomDataStore object available to the objects in a form, use a TDecisionCube object.


TCustomDataStore properties

TCustomDataStore	Alphabetically	Legend

In TCustomDataStore

BinData

Capacity

CurrentSummary

DataSet

DimensionCount

DimensionMap

DimensionMapCount

MaxCells

MaxDimensions

MaxSummaries

ShowProgressDialog

SummaryCount

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TCustomDataStore properties

TCustomDataStore	By object	Legend

BinData

Capacity

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

CurrentSummary

DataSet

DesignInfo

DimensionCount

DimensionMap

DimensionMapCount

MaxCells

MaxDimensions

MaxSummaries

Name

Owner

ShowProgressDialog

SummaryCount

Tag

VCLComObject


TCustomDataStore::BinData

TCustomDataStore	See also

Indicates whether all the dimensions in the multidimensional array include a cell for every value along the dimension.

__property bool BinData = {read=FBinData, write=SetBinData, nodefault};

Description

Read BinData to determine whether any of the active dimensions have been grouped into ranges or been put into a paged (permanently drilled) state. When BinData is true, at least one dimension has been paged or has been collapsed into ranges of values. When BinData is false, all dimensions include entries for every value of the dimension field that appears in the dataset.


TCustomDataStore::Capacity

TCustomDataStore	See also

Limits the memory that may be used by the cached array of summary values.

__property int Capacity = {read=GetCapacity, write=SetCapacity, nodefault};

Description

Set Capacity to limit the number of bytes that may be used by the crosstabulated data store for storing the multidimensional array of summary values. If the number of active dimensions and summaries causes the cache to exceed this value, an ELowCapacityError is thrown.


TCustomDataStore::CurrentSummary

TCustomDataStore	See also

Specifies the index of the current summary from the set of active summaries maintained by the crosstabulated data store.

__property int CurrentSummary = {read=GetCurrentSummary, write=SetCurrentSummary, nodefault};

Description

Use CurrentSummary to determine which of the active summaries is used to provide values to clients of the data store. CurrentSummary returns 0 if the first active summary is the current summary. CurrentSummary returns SummaryCount-1 if the last active summary is the current summary.

The dataset specified by the DataSet property provides all the fields that make up the dimensions and summaries of the dimension map. At any time, a subset of all the dimensions and summaries provided by the dataset is cached by the crosstabulated data store and available to decision source objects. Of all the active (cached) summaries, only one can be provided to decision source objects at a time. That one summary is CurrentSummary.


TCustomDataStore::DataSet

TCustomDataStore	See also

Specifies the dataset that provides the fields which make up the dimensions and summaries maintained by the crosstabulated data store.

__property Db::TDataSet* DataSet = {read=GetDataSet, write=SetDataSet};

Description

Set DataSet to the dataset that contains the crosstabulated data for the data store. Usually, DataSet is a TDecisionQuery object. TDecisionQuery objects are SQL queries that are grouped appropriately to calculate summaries for a crosstabulated data store.

The DataSet property can also be set to a TQuery object where the SQL has the same form as that of a TDecisionQuery or to any other dataset that contains summarized values in the same structure as the result of a TDecisionQuery query.

If the DataSet property is a TQuery or TDecisionQuery object, the crosstabulated data store automatically determines which fields are dimensions and which are summaries. If the DataSet property is not a query, the fields in the dimension map must be explicitly identified as dimensions or summaries, and, if they represent summaries, the type of summary must be indicated.

Note:	The summary values for the crosstabulated data store must be calculated by the TDataSet object. The data store does not summarize raw data, but analyzes summarized data into dimensions.


TCustomDataStore::DimensionCount

TCustomDataStore	See also

Specifies the number of dimensions cached by the crosstabulated data store.

__property int DimensionCount = {read=GetDimensionCount, nodefault};

Description

Read DimensionCount to determine the number of active dimensions. The dataset specified by the DataSet property provides all the fields that make up the dimensions and summaries of the dimension map. At any time, a subset of all the dimensions and summaries provided by the dataset is cached by the crosstabulated data store and available to decision source objects. DimensionCount is the number of active (cached) dimensions that can be provided to decision source objects.


TCustomDataStore::DimensionMap

TCustomDataStore	See also

Describes the dimensions and summaries maintained by the crosstabulated data store.

__property TCubeDims* DimensionMap = {read=FDimensionMap, write=FDimensionMap};

Description

Read DimensionMap to access the dimensions and summaries of the data store. The individual entries of the dimension map represent the fields of the dataset specified by the DataSet property or calculated fields derived from those fields, such as averages. DimensionMap provides information about these fields from the dataset that make up the crosstabulated data store, including the field names and the use of the fields within the multidimensional array.

When the data store is not active, use the properties of the TCubeDim objects to change the information cached by the data store. Use the ActiveFlag property of individual TCubeDim objects to specify whether those dimensions or summaries from the dataset are cached by the crosstabulated data store. Use the BinType property of the TCubeDim objects to allow cells along temporal dimensions to represent date ranges or to put the dimensions in a paged (permanently drilled) state.

If the dataset is not a query, use the DimensionType property of the TCubeDim objects to identify which fields are dimensions and which are summaries, and to identify the type of summary represented by the summary fields.

To change the properties of the entries in the dimension map when the data store is active, use the Refresh method.

Note:	At design time, the DimensionType, Name, and ActiveFlag properties of the TCubeDim objects that make up the dimension map can be set using the Decision Cube Editor.


TCustomDataStore::DimensionMapCount

TCustomDataStore	See also

Specifies the total number of fields from the dataset that make up the dimensions and summaries of the dimension map.

__property int DimensionMapCount = {read=GetDimensionMapCount, nodefault};

Description

Read DimensionMapCount to determine the number of TCubeDim objects that can be accessed through the DimensionMap property. The value of DimensionMapCount is the number of fields in the dataset specified by the DataSet property plus the number of derived fields based on those fields, such as fields for average values that are derived from count and summary fields.

The value of DimensionMapCount is not the same as DimensionCount + SummaryCount. DimensionCount and SummaryCount count the number of dimensions and summaries that are cached by the crosstabulated data cube and available to the decision source. DimensionMapCount also counts any inactive dimensions or summaries that are not included in the cache.


TCustomDataStore::MaxCells

TCustomDataStore	See also

Limits the number of cells that can be included in the cache at any one time.

__property int MaxCells = {read=FMaxCells, write=FMaxCells, nodefault};

Description

Use MaxCells to limit the memory usage of the crosstabulated data store. Memory consumption increases geometrically with each dimension that is cached in the multidimensional array and linearly with each summary. MaxCells prevents too many dimensions or summaries from being cached at once.

When the ActiveFlag property of a dimension or summary is diActive, it is always added to the cache. When the ActiveFlag property of a dimension or summary is diAsNeeded, it can be added only if it does not cause the number of cells to exceed MaxCells. The data store swaps in as-needed dimensions and summaries when they are used by the decision source, making room, if necessary, by swapping out closed dimensions or summaries that are not current.

Note:	Be sure to set MaxCells to a value big enough to accommodate all active dimensions and summaries plus the number of as-needed dimensions and summaries that can be open at one time.


TCustomDataStore::MaxDimensions

TCustomDataStore	See also

Limits the number of dimensions that can be cached by the crosstabulated data store at any one time.

__property int MaxDimensions = {read=FMaxDims, write=SetMaxDims, nodefault};

Description

Use MaxDimensions to limit the memory usage of the data store. Memory consumption increases geometrically with each dimension that is cached in the multidimensional array. MaxDimensions prevents too many dimensions to be cached at once.

When the ActiveFlag property of a dimension is diActive, the dimension is always added to the cache. When the ActiveFlag property of a dimension is diAsNeeded, it can be added only if it does not cause the number of active dimensions to exceed MaxDimensions. The data store swaps in as-needed dimensions when they are open in the decision source, making room, if necessary, by swapping out closed dimensions.

Note:	Be sure to set MaxDimensions to a value big enough to accommodate all active dimensions plus the number of as-needed dimensions that can be open at one time.


TCustomDataStore::MaxSummaries

TCustomDataStore	See also

Limits the number of summaries that can be cached by the crosstabulated data store at one time.

__property int MaxSummaries = {read=FMaxSums, write=SetMaxSums, nodefault};

Description

Use MaxSummaries to limit the memory usage of the data store. Memory consumption increases linearly with each summary that is cached in the multidimensional array. MaxSummaries prevents too many summaries to be cached at once.

When the ActiveFlag property of a summary is diActive, the summary is always added to the cache. When the ActiveFlag property is diAsNeeded, it can be added only if it does not cause the number of active summaries to exceed MaxSummaries. The data store swaps in as-needed summaries when they are chosen as the current summary, making room, if necessary, by swapping out other as-needed summaries.


TCustomDataStore::ShowProgressDialog

TCustomDataStore	See also

Determines whether a progress bar appears when the cache of crosstabulated values is built.

__property bool ShowProgressDialog = {read=FShowProgress, write=FShowProgress, nodefault};

Description

Set ShowProgressDialog to specify whether a progress bar should appear to provide users with a visual indication when the cache is being built. If the crosstabulated data store includes may dimensions, rebuilding the cache can take a noticeable amount of time. The progress bar provides users with feedback about how long this process will take.


TCustomDataStore::SummaryCount

TCustomDataStore	See also

Specifies the number of summary fields cached by the crosstabulated data store.

__property int SummaryCount = {read=GetSummaryCount, nodefault};

Description

Read SummaryCount to determine the number of active summaries in the dimension map. The dataset specified by the DataSet property provides all the fields that make up the dimensions and summaries of the dimension map. At any time, a subset of all the dimensions and summaries provided by the dataset is cached by the crosstabulated data store and available to decision source objects. SummaryCount is the number of active (cached) summaries that can provide data to decision source objects.


TCustomDataStore events

TCustomDataStore	Alphabetically

In TCustomDataStore

AfterClose

AfterOpen

BeforeClose

BeforeOpen

OnLowCapacity

OnRefresh


TCustomDataStore events

TCustomDataStore	By object

AfterClose

AfterOpen

BeforeClose

BeforeOpen

OnLowCapacity

OnRefresh


TCustomDataStore::AfterClose

TCustomDataStore	See also

Occurs immediately after the crosstabulated data store has been deactivated.

typedef void __fastcall (__closure *TCubeNotifyEvent)(TCustomDataStore* DataCube);

__property TCubeNotifyEvent AfterClose = {read=FAfterClose, write=FAfterClose};

Description

Write an AfterClose event handler to take specific action when the crosstabulated data store has been shut down. For example, an application could provide feedback about the state of the data store, or update the dimension map for the next time the data store is activated.


TCustomDataStore::AfterOpen

TCustomDataStore	See also

Occurs immediately after the crosstabulated data store has been activated.

typedef void __fastcall (__closure *TCubeNotifyEvent)(TCustomDataStore* DataCube);

__property TCubeNotifyEvent AfterOpen = {read=FAfterOpen, write=FAfterOpen};

Description

Write an AfterOpen event handler to take specific action when the crosstabulated data store is activated. This is the first opportunity to determine how much memory is consumed by the multidimensional cache maintained by the data store.


TCustomDataStore::BeforeClose

TCustomDataStore	See also

Occurs immediately before the crosstabulated data store is deactivated.

typedef void __fastcall (__closure *TCubeNotifyEvent)(TCustomDataStore* DataCube);

__property TCubeNotifyEvent BeforeClose = {read=FBeforeClose, write=FBeforeClose};

Description

Write a BeforeClose event handler to take specific action before the data store shuts down. For example, an application can store information about the current state of the cache before it is cleared and all associated memory freed.


TCustomDataStore::BeforeOpen

TCustomDataStore	See also

Occurs immediately before the crosstabulated data store is activated.

typedef void __fastcall (__closure *TCubeNotifyEvent)(TCustomDataStore* DataCube);

__property TCubeNotifyEvent BeforeOpen = {read=FBeforeOpen, write=FBeforeOpen};

Description

Write a BeforeOpen event handler to take specific action before the crosstabulated data store is activated. This is an appropriate time to adjust the value of Capacity, or set the ShowProgressDialog based on the number of active dimensions in the DimensionMap.

This is the last opportunity to adjust the entries in the DimensionMap before the cache is built. If the data store has never been active before this, the DimensionMap property will be NULL at this point. A BeforeOpen event handler can build a dimension map programmatically if it is NULL. If the dimension map is not NULL, the properties of the dimension items can be changed, but the order and number of the dimension items themselves should not be changed.


TCustomDataStore::OnLowCapacity

TCustomDataStore	See also

Occurs when the multidimensional cache requires more memory than is allowed by the Capacity property.

enum TErrorAction { eaFail, eaContinue };

typedef void __fastcall (__closure *TCapacityErrorEvent)(TErrorAction &Action);

__property TCapacityErrorEvent OnLowCapacity = {read=FOnCapacityError, write=FOnCapacityError};

Description

Write an OnLowCapacity event handler to respond to ELowCapacityError exceptions. An OnLowCapacity event handler can change the value of Capacity or deactivate some of the dimensions in the dimension map in order to allow the cache to fit in the available memory. If the memory problem is handled by the OnLowCapacity event handler, change the Action parameter to eaContinue to allow the data store to continue building the cache. Otherwise, an ELowCapacityError exception will be thrown.


TCustomDataStore::OnRefresh

TCustomDataStore	See also

Occurs immediately before the dimension map is changed.

typedef void __fastcall (__closure *TCubeRefreshEvent)(TCustomDataStore* DataCube, TCubeDims* DimMap);

__property TCubeRefreshEvent OnRefresh = {read=FOnRefresh, write=FOnRefresh};

Description

Write an OnRefresh event handler to take specific action when the dimension map changes. The DimMap parameter specifies the new value that is about to be set for the DimensionMap property. Use an OnRefresh event handler to change the properties of these dimension items before the DimensionMap property is set and the cache is rebuilt. This is also an opportunity to reset the MaxDimensions or MaxSummaries property to accommodate the dimension map that is about to be set.


TCustomDataStore methods

TCustomDataStore	Alphabetically

In TCustomDataStore

~TCustomDataStore

GetDimensionMemberCount

GetDimensionName

GetMemberAsString

GetMemberAsVariant

GetMemoryUsage

GetSummaryAsString

GetSummaryAsVariant

GetSummaryName

Refresh

TCustomDataStore

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TCustomDataStore methods

TCustomDataStore	By object

~TCustomDataStore

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetDimensionMemberCount

GetDimensionName

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMemberAsString

GetMemberAsVariant

GetMemoryUsage

GetNamePath

GetParentComponent

GetSummaryAsString

GetSummaryAsVariant

GetSummaryName

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Refresh

RemoveComponent

SafeCallException

TCustomDataStore


TCustomDataStore::TCustomDataStore

TCustomDataStore	See also

Creates an instance of TCustomDataStore.

__fastcall virtual TCustomDataStore(Classes::TComponent* AOwner);

Description

Do not create instances of TCustomDataStore. Instead, create a descendant of TCustomDataStore such a TDecisionCube.

TCustomDataStore allocates the helper objects used by the crosstabulated data store to manage the dimension map and the crosstabulated data.


TCustomDataStore::~TCustomDataStore

TCustomDataStore	See also

Destroys an instance of TCustomDataStore.

__fastcall virtual ~TCustomDataStore(void);

Description

Do not call the ~TCustomDataStore method directly. Instead use the delete keyword.


TCustomDataStore::GetDimensionMemberCount

TCustomDataStore	See also

Returns the number of distinct values for a dimension of the data store.

virtual int __fastcall GetDimensionMemberCount(int Dimension);

Description

Call GetDimensionMemberCount to determine the number of distinct field values in the dimension specified by the Dimension parameter. Zero specifies the first active dimension, and DimensionCount-1 specifies the last active dimension.

To obtain the individual values of the dimension, use the GetMemberAsString or GetMemberAsVariant method. GetDimensionMemberCount returns a value that provides an upper limit to the Index parameter of the GetMemberAsString or GetMemberAsVariant method.

To obtain the name of the dimension referred to by the Dimension parameter, use the GetDimensionName method.


TCustomDataStore::GetDimensionName

TCustomDataStore	See also

Returns the name of an active dimension.

virtual System::AnsiString __fastcall GetDimensionName(int Dimension);

Description

Call GetDimensionName to obtain the name of the dimension indexed by the Dimension parameter. Zero specifies the first active dimension and DimensionCount-1 specifies the last active dimension. The name of a dimension is the name of the database field the dimension represents, unless the Name property of the corresponding TDimensionItem object is changed.


TCustomDataStore::GetMemberAsString

TCustomDataStore	See also

Returns the specified value from a dimension of the data store, formatted as a string.

virtual System::AnsiString __fastcall GetMemberAsString(int Dimension, int Index);

Description

Call GetMemberAsString to retrieve one of the values from the dimension specified by the Dimension parameter. Zero specifies the first dimension, and DimensionCount-1 specifies the last dimension. The Index parameter indicates which value along the dimension is returned, where 0 is the first value. GetDimensionMemberCount returns the number of values included in the dimension.

GetMemberAsString returns a field value formatted as a string. To obtain the field value as an unformatted variant, use the GetMemberAsVariant method.


TCustomDataStore::GetMemberAsVariant

TCustomDataStore	See also

Returns the specified value from a dimension of the crosstabulated data store.

System::Variant __fastcall GetMemberAsVariant(int Dimension, int Index);

Description

Call GetMemberAsVariant to retrieve one of the values from the dimension specified by the Dimension parameter. Zero specifies the first dimension, and DimensionCount-1 specifies the last dimension. The Index parameter indicates which value along the dimension is returned, where 0 is the first value. GetDimensionMemberCount returns the number of values included in the dimension.


TCustomDataStore::GetMemoryUsage

TCustomDataStore	See also

Returns the number of bytes of memory used to cache the multidimensional array of summaries along all active dimensions.

int __fastcall GetMemoryUsage(void);

Description

Call GetMemoryUsage to determine the size of the cache that stores the crosstabulated information for the data store. If the returned value is too large, consider making some of the active dimensions paged by setting their BinType property to binSet or allowing the data store to swap some dimensions out by setting their ActiveFlag property to diAsNeeded. The cube dimension can be accessed using the DimensionMap property.

The storage needs of the crosstabulated data store increase geometrically with each active dimension that is added. Applications must find the best balance between the performance benefit of caching many dimensions so that they are immediately available to decision controls, and the need to keep the number of active dimensions small enough so that the cache does not consume inordinate amounts of memory.


TCustomDataStore::GetSummaryAsString

TCustomDataStore	See also

Returns the value of the current summary for a set of values along all the active dimensions.

virtual System::AnsiString __fastcall GetSummaryAsString(Mxarrays::TSmallIntArray* Coord);

Description

Call GetSummaryAsString to obtain the value of a single cell from the multidimensional array of summary values. Set the Coord parameter to an array of indexes, where each index identifies a value along one of the dimensions of the array. The first value of Coord is the index of the desired value along the first active dimension, the second value of Coord is the index of the desired value along the second active dimension, and so on. Coord should contain DimensionCount values.

To obtain the names of the active dimensions that correspond to the entries in the Coord parameter, use the GetDimensionName method. To obtain the name of the specified value along any of the dimensions, use the GetMemberAsString method.

GetSummaryAsString formats the summarized value as a string. To obtain the summary as a variant, use the GetSummaryAsVariant method.


TCustomDataStore::GetSummaryAsVariant

TCustomDataStore	See also

Returns the value of the current summary for a set of values along all the active dimensions.

virtual System::Variant __fastcall GetSummaryAsVariant(Mxarrays::TSmallIntArray* Coord);

Description

Call GetSummaryAsVariant to obtain the value of a single cell from the multidimensional array of summary values. Set the Coord parameter to an array of indexes, where each index identifies a value along one of the dimensions of the array. The first value of Coord is the index of the desired value along the first active dimension, the second value of Coord is the index of the desired value along the second active dimension, and so on. Coord should contain DimensionCount values.

To obtain the names of the active dimensions that correspond to the entries in the Coord parameter, use the GetDimensionName method. To obtain the name of the specified value along any of the dimensions, use the GetMemberAsString method.

To obtain the summary formatted as a string, use the GetSummaryAsString method.


TCustomDataStore::GetSummaryName

TCustomDataStore	See also

Returns the name of an active summary.

virtual System::AnsiString __fastcall GetSummaryName(int ISum);

Description

Call GetSummaryName to obtain the name of the summary specified by the ISum parameter. Zero specifies the first active summary and SummaryCount-1 specifies the last active summary.


TCustomDataStore::Refresh

TCustomDataStore	See also

Updates the dimension map of the crosstabulated data store.

void __fastcall Refresh(TCubeDims* DimMap, bool bForce);

Description

To change the properties of the dimensions in the dimension map, make a copy of the DimensionMap property, make any desired changes to the properties of the TCubeDim objects, and call Refresh, passing in the altered dimension map. The bForce parameter specifies whether the cache should be rebuilt unconditionally. When bForce is false, the cache will not be rebuilt unless the changes require it.

When the data store is active, call Refresh rather than directly altering the dimension map. Do not call Refresh while the data store is building the cache. Use the BeforeOpen and AfterOpen events to determine when the cache is being rebuilt.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent


TDateField

Hierarchy	Properties	Methods	Events	See also

TDateField represents a date field in a dataset.

Unit

db

Description

Date fields contain date values.

DateField introduces no new properties, events, or methods. It overrides the DataSize property and constructor to reflect the specifics of a field of type ftDate.

As a descendant of TDateTimeField, TDateField includes many properties, methods, and events that are useful for managing the value and properties of a temporal field in a database.


TDateField properties

TDateField	Alphabetically	Legend

In TDateField

DataSize

Derived from TDateTimeField

AsDateTime

AsFloat

AsString

AsVariant

DisplayFormat

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDateField properties

TDateField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TDateField::DataSize
DataSize

Example

Specifies the amount of memory needed to store the value of a date field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a date field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For date fields, DataSize is always 4. This is the size of date values in the database tables, not the size of the TDateTime data type used to store and manipulate date values by TDateField.


TDateField events

TDateField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TDateField events

TDateField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TDateField methods

TDateField	Alphabetically

In TDateField

~TDateField

Create

TDateField

Derived from TField

Assign

AssignValue

Clear

Destroy

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDateField methods

TDateField	By object

~TDateField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

Create

DefaultHandler

Destroy

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TDateField

Validate


TDateField::TDateField

TDateField	See also

Creates an instance of TDateField.

__fastcall virtual TDateField(Classes::TComponent* AOwner);

Description

Do not call TDateField directly in an application. Instead, use the new keyword to obtain an indirect reference to a new instance of TDateField. It is seldom necessary for applications to instantiate TDateField because a date field object is created automatically for all date fields in a dataset.

After calling the parent object's constructor, TDateField sets the DataType to ftDate.


TDateField::~TDateField

TDateField

Frees the memory associated with the TDateField object.

__fastcall virtual ~TDateField(void) { }

Description

Do not call ~TDateField directly. Instead, use the delete keyword on the object, which causes ~TDateField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TDateTimeField


TDateTimeField

Hierarchy	Properties	Methods	Events	See also

TDateTimeField represents a date-time field in a dataset.

Unit

db

Description

Date-time fields contain combined date and time information, sometimes called timestamps.

TDateTimeField introduces new properties to convert between date-time values and other data types, and to format the value of a date-time field for display. As a descendant of TField, TDateTimeField includes many properties, methods, and events that are useful for managing the value and properties of a field in a database.

TDateTimeField is also the direct ancestor of two other temporal field types: TDateField and TTimeField.


TDateTimeField properties

TDateTimeField	Alphabetically	Legend

In TDateTimeField

AsDateTime

AsFloat

AsString

AsVariant

DataSize

DisplayFormat

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDateTimeField properties

TDateTimeField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TDateTimeField::AsDateTime

TDateTimeField	See also 	Example

Represents the value of the date-time field as a TDateTime value.

__property System::TDateTime AsDateTime = {read=GetAsDateTime, write=SetAsDateTime};

Description

Use AsDateTime to

•	Assign a date-time value to a date-time field.

•	Assign the date-time field value to a date-time variable.

The time portion of the date-time value is ignored when setting the AsDateTime property on a field where the DataType is ftDate. The date portion of the date-time value is ignored when setting the AsDateTime property on a field where the DataType is ftTime.

Similarly, reading the AsDateTime property of a field with DataType set to ftDate yields a date-time value of 12:00 a::m. on the date value of the field. Reading the AsDateTime property of a field with DataType set to ftTime yields a date-time value of the time value of the field on Dec. 30, 1899.

Reading or setting the AsDateTime property for a field with DataType set to ftDateTime treats both the date and time portions of the date-time value as meaningful.

AsDateTime uses date-time values stored in the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.

Following are some examples of TDateTime values and their corresponding dates and times:

Value	Date and time

0	Dec. 30 1899 12:00 a::m.

2::75	Jan. 1 1900 6:00 p::m.

-1::25	Dec. 29 1899 6:00 a::m.

35065	Jan. 1 1996 12:00 a::m.

To find the number of days between two dates, simply subtract the two values. Likewise, to increment a date and time value by a certain fractional number of days, simply add the fractional number to the date and time value.

Note:	Because TDateTimeField stores date and time values in the TDateTime type, AsDateTime is the same as Value for date-time fields. Use AsDateTime when working with field components where the actual class of the object is not known.


TDateTimeField::AsFloat

TDateTimeField	See also

Represents the value of the date-time field as a floating-point value.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

Use AsFloat to

•	Assign a floating-point value to a date-time field.

•	Assign the date-time field value to a floating-point variable.

For example, this code assigns a floating-point value to date-time field value:

MyDateTimeField->AsFloat = 35065.75; // Jan 1, 1996 6:00 p.m.

To assign date-time field value to a floating-point value, use code similar to this:

FloatVariable = MyDateTimeField->AsFloat;

TDateTimeField converts dates to the number of days that have passed since Dec. 30 1899. Time values are converted to the fraction of a 24-hour day that has elapsed. The floating-point value for a date-time quantity is the sum of the date and time values.

The fractional (time) portion of the floating-point value is ignored when setting the AsFloat property on a field where the DataType is ftDate. The integral (date) portion of the floating-point value is ignored when setting the AsFloat property on a field where the DataType is ftTime.

Similarly, reading the AsFloat property of a field with DataType set to ftDate yields a floating-point value with no fractional (time) part. Reading the AsFloat property of a field with DataType set to ftTime yields a floating-point value greater than -1 and less than 1.


TDateTimeField::AsString

TDateTimeField	See also

Represents the value of the date-time field as a string.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to

•	Assign a string to a date-time field.

•	Assign the date-time field value to a string.

For example, this code assigns a string to a date-time field value:

MyDateTimeField->AsString = "1/1/1997 8:00 am";

To assign date-time field value to a floating-point variable, use code similar to this:

StringVariable = MyDateTimeField->AsString;

If the DataType property value of the date-time field is ftDate, setting the AsString property uses the StrToDate function to convert the string to a date value. If the DataType is ftTime, setting the AsString property uses the StrToTime function. If the DataType is ftDateTime, setting the AsString property uses the StrToDateTime function.

If the DisplayFormat property is set, reading the AsString property yields the value of the date-time field formatted according to the DisplayFormat. If DisplayFormat has not been set, reading the AsString property yields the value of the date-time field formatted using the date and time format specified by the Windows Control Panel.


TDateTimeField::AsVariant

TDateTimeField	See also

Represents the value of a date-time field as a variant value.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the date-time field value to variant variable.

•	Assign a variant value to the date-time field.

Using variants is useful when the actual field type and the data type are unknown.


TDateTimeField::DataSize

TDateTimeField	See also 	Example

Specifies the amount of memory needed to store the value of a date-time field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a date-time field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For date-time fields, DataSize is always 8.


TDateTimeField::DisplayFormat

TDateTimeField	See also

Controls the formatting of the date-time field for display purposes.

__property System::AnsiString DisplayFormat = {read=FDisplayFormat, write=SetDisplayFormat};

Description

Use DisplayFormat to specify a formatting string that is used to format the value in a date-time field when the field’s value appears as a string.

If DisplayFormat is not assigned a string, the value is formatted according to the default specified by the Windows Control Panel.

Construct a DisplayFormat string using these format specifiers:

Specifier	Displays

c	The date using the format given by the ShortDateFormat global variable, followed by the time using the format given by the LongTimeFormat global variable. The time is not displayed if the fractional part of the DateTime value is zero.

d	The day as a number without a leading zero (1-31).

dd	The day as a number with a leading zero (01-31).

ddd	The day as an abbreviation (Sun-Sat) using the strings given by the ShortDayNames global variable.

dddd	The day as a full name (Sunday-Saturday) using the strings given by the LongDayNames global variable.

ddddd	The date using the format given by the ShortDateFormat global variable.

dddddd	The date using the format given by the LongDateFormat global variable.

m	The month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mm	The month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mmm	The month as an abbreviation (Jan-Dec) using the strings given by the ShortMonthNames global variable.

mmmm	The month as a full name (January-December) using the strings given by the LongMonthNames global variable.

yy	The year as a two-digit number (00-99).

yyyy	The year as a four-digit number (0000-9999).

h	The hour without a leading zero (0-23).

hh	The hour with a leading zero (00-23).

n	The minute without a leading zero (0-59).

nn	The minute with a leading zero (00-59).

s	The second without a leading zero (0-59).

ss	The second with a leading zero (00-59).

t	The time using the format given by the ShortTimeFormat global variable.

tt	The time using the format given by the LongTimeFormat global variable.

am/pm	The time using the 12-hour clock for the preceding h or hh specifier, followed by "am" for any hour before noon, or "pm" for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

a/p	The time using the 12-hour clock for the preceding h or hh specifier, followed by "a" for any hour before noon, or "p" for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

ampm	The time using the 12-hour clock for the preceding h or hh specifier, followed by the contents of the TimeAMString global variable for any hour before noon, or the contents of the TimePMString global variable for any hour after noon.

/	The date separator character given by the DateSeparator global variable.

:	The time separator character given by the TimeSeparator global variable.

'xx'/"xx"	Characters enclosed in single or double quotes are displayed as-is, with no formatting changes.

Format specifiers may be written in uppercase or lowercase letters; both produce the same result.

If the string given by the Format parameter is empty, the date and time value is formatted as if a c format specifier had been given.


TDateTimeField::Value

TDateTimeField	See also

Represents the value of the data in the date-time field.

__property System::TDateTime Value = {read=GetAsDateTime, write=SetAsDateTime};

Description

Use Value to read data directly from and write data directly to a date-time field component at runtime. TDateTimeField components store and manipulate their data as TDateTime values. Thus, for date-time fields, the Value property is the same as the AsDateTime property.


TDateTimeField events

TDateTimeField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TDateTimeField events

TDateTimeField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TDateTimeField methods

TDateTimeField	Alphabetically

In TDateTimeField

~TDateTimeField

TDateTimeField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDateTimeField methods

TDateTimeField	By object

~TDateTimeField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TDateTimeField

Validate


TDateTimeField::TDateTimeField

TDateTimeField	See also

Creates and initializes a TDateTimeField object.

__fastcall virtual TDateTimeField(Classes::TComponent* AOwner);

Description

Do not call the constructor for TDateTimeField directly. Instead, use the new keyword when instantiating a TDateTime field at runtime. It is seldom necessary to call TDateTimeField directly, because a date-time field object is instantiated automatically for all date-time fields in a dataset.

After calling the parent object's constructor, TDateTimeField sets the DataType to ftDateTime.


TDateTimeField::~TDateTimeField

TDateTimeField

~TDateTimeField frees the memory associated with the TDateTimeField object.

__fastcall virtual ~TDateTimeField(void) { }

Description

Do not call ~TDateTimeField directly. Instead, use the delete keyword on the object, which causes ~TDateTimeField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField


TDataSourceLink

Hierarchy	Properties	Methods	See also

TDataSourceLink helps manage the link to the data source for a TDBLookupControl object.

Unit

dbctrls

Description

TDataSourceLink is tailored to work with TDBLookupControl. It should only be used by the TDBLookupControl class.


TDataSourceLink properties

TDataSourceLink	Alphabetically	Legend

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TDataSourceLink properties

TDataSourceLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TDataSourceLink methods

TDataSourceLink	Alphabetically	Legend

In TDataSourceLink

~TDataSourceLink

ActiveChanged

FocusControl

RecordChanged

TDataSourceLink

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDataSourceLink methods

TDataSourceLink	By object	Legend

~TDataSourceLink

ActiveChanged

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Edit

FieldAddress

FocusControl

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RecordChanged

SafeCallException

TDataSourceLink

UpdateRecord


TDataSourceLink::ActiveChanged

TDataSourceLink	See also

Informs the TDBLookupControl of changes in the Active property of its DataSource.

virtual void __fastcall ActiveChanged(void);

Description

Applications can not call the ActiveChanged procedure directly. Changes in the Active property trigger this procedure. When the Active property becomes true, ActiveChanged causes the TDBLookupControl object to reacquire its DataField property. This ensures that the lookup control is working with the correct field component.


TDataSourceLink::FocusControl

TDataSourceLink	See also

Moves input focus to the data field of the TDBLookupControl object.

virtual void __fastcall FocusControl(Db::TFieldRef Field);

Description

Applications can not call the FocusControl procedure. It is called automatically when a field component in the DataSet tries to set focus to a control on the form that represents the field. FocusControl moves focus to the DataField of the TDBLookupControl if it matches the Field parameter.


TDataSourceLink::RecordChanged

TDataSourceLink	See also

Informs the TDBLookupControl of changes in the current record or field of the DataSource.

virtual void __fastcall RecordChanged(Db::TField* Field);

Description

Applications can not call RecordChanged directly. It is triggered automatically after changes in the contents of the current record. If the Field parameter is the key field of the lookup control, or if the Field parameter is NULL, indicating that the entire record changed, RecordChanged causes the lookup control to refetch the value of its key field.


Accessibility

Read-only


TDataSourceLink::TDataSourceLink

TDataSourceLink

Creates a new TDataSourceLink object.

__fastcall TDataSourceLink(void) : Db::TDataLink() { }

Description

Do not create instances of TDataSourceLink. It is created automatically from the constructor of the associated TDBLookupControl.


TDataSourceLink::~TDataSourceLink

TDataSourceLink

~TDataSourceLink frees the memory associated with the TDataSourceLink object.

__fastcall virtual ~TDataSourceLink(void) { }

Description

Do not call ~TDataSourceLink directly. Instead, use the delete keyword on the object, which causes ~TDataSourceLink to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


 TDBCheckBox

Hierarchy	Properties	Methods	Events	See also

TDBCheckBox is a data aware control that allows the user to select or deselect a single value.

Unit

dbctrls

Description

Use TDBCheckBox to place a data-aware check box on a form. A check box presents an option to the user; the user can check it to select the option or uncheck it to deselect the option. A database check box (TDBCheckBox) is much like an ordinary check box (TCheckBox), except that it is aware of the data in a particular field of a dataset. Because check boxes can represent only two values (checked and unchecked), database check boxes are most appropriate for boolean fields. They can, however, be used to group the values of any field into two sets.

For applications that don’t require the data-aware capabilities of TDBCheckBox, use TCheckBox instead to conserve system resources.


TDBCheckBox properties

TDBCheckBox	Alphabetically	Legend

In TDBCheckBox

DataField

DataSource

Field

ReadOnly

ValueChecked

ValueUnchecked

Derived from TCustomCheckBox

Alignment

AllowGrayed

Checked

State

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBCheckBox properties

TDBCheckBox	By object	Legend

Align

Alignment

AllowGrayed

BoundsRect

Brush

Caption

Checked

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

ShowHint

Showing

State

TabOrder

TabStop

Tag

Top

ValueChecked

ValueUnchecked

VCLComObject

Visible

Width

WindowProc


TDBCheckBox::DataField

TDBCheckBox	See also

Identifies the field from which the data-aware control displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Set DataField to the field name of the field component that the check box represents. The dataset the field is located in is specified by the DataSource property.


TDBCheckBox::DataSource

TDBCheckBox	See also

Links the check box to a dataset.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Specify the data source component that identifies the dataset in which the data is found. To allow the check box to represent the data for a field, both the DataSource and the DataField properties must be set.


TDBCheckBox::Field

TDBCheckBox	See also

Indicates the TField object whose current value the check box represents.

__property Db::TField* Field = {read=GetField};

Description

Use the Field object when you want to change the value of the data in the field programmatically.


TDBCheckBox::ReadOnly

TDBCheckBox	See also

Determines whether the user can change the value of the field.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Use ReadOnly to specify whether the check box allows the user to change the field value by checking or unchecking the box. When ReadOnly is true, the checkbox can only be used to display the value of the field on the current record. When ReadOnly is false, the user can use the check box to change the field value.


TDBCheckBox::ValueChecked

TDBCheckBox	See also

Specifies the field value that corresponds to the checked state of the checkbox.

__property System::AnsiString ValueChecked = {read=FValueCheck, write=SetValueCheck};

Description

Use ValueChecked to specify the field value represented by the check box when it is checked. If the value of the ValueChecked property is equal to the data in the field of the current record of the dataset, the database check box appears checked. When the user checks the database check box, the field value is set to ValueChecked.

ValueChecked can represent more than one value in a semicolon-delimited list of items. If any of the items matches the contents of the field of the current record in the dataset, the check box appears checked. For example, set the value of ValueChecked string like this:

If the contents of the associated field is the string true, Yes, or On, the check box is checked. The value of the field is compared to ValueChecked in a case-insensitive comparison. If the user selects a check box where ValueChecked represents more than one value, the first item in the list is assigned to the field.

If the contents of the field of the current record matches a string specified as the value of the ValueUnchecked property, the check box appears unchecked. If the contents of the field matches no string in either ValueChecked or ValueUnchecked, the check box appears gray.

Note:	If the DataField of the database check box is a logical field, the check box is always checked if the contents of the field is true, and it is always unchecked if the contents of the field is false. The values of the ValueChecked and ValueUnchecked properties have no affect on logical fields.


TDBCheckBox::ValueUnchecked

TDBCheckBox	See also

Specifies the field value that corresponds to the unchecked state of the checkbox.

__property System::AnsiString ValueUnchecked = {read=FValueUncheck, write=SetValueUncheck};

Description

Use ValueUnchecked to specify the field value represented by the check box when it is unchecked. If the value of the ValueUnchecked property is equal to the data in the field of the current record of the dataset, the database check box appears unchecked. When the user unchecks the database check box, the field value is set to ValueUnchecked.

ValueUnchecked can represent more than one value in a semicolon-delimited list of items. If any of the items matches the contents of the field of the current record in the dataset, the check box appears unchecked. For example, set the value of ValueUnchecked string like this:

If the contents of the associated field is the string false, No, or Off, the check box appears unchecked. The value of the field is compared to ValueUnchecked in a case-insensitive comparison. If the user unchecks a check box where ValueUnchecked represents more than one value, the first item in the list is assigned to the field.

If the contents of the field of the current record matches a string specified as the value of the ValueChecked property, the check box appears checked. If the contents of the field matches no string in either ValueChecked or ValueUnchecked, the check box appears gray.

Note:	If the DataField of the database check box is a logical field, the check box is always unchecked if the contents of the field is false, and it is always checked if the contents of the field is true. The values of the ValueChecked and ValueUnchecked properties have no affect on logical fields.


TDBCheckBox events

TDBCheckBox	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBCheckBox events

TDBCheckBox	By object	Legend

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBCheckBox methods

TDBCheckBox	Alphabetically

In TDBCheckBox

~TDBCheckBox

TDBCheckBox

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBCheckBox methods

TDBCheckBox	By object

~TDBCheckBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBCheckBox

Update

UpdateControlState


TDBCheckBox::TDBCheckBox

TDBCheckBox	See also

Creates an instance of TDBCheckBox.

__fastcall virtual TDBCheckBox(Classes::TComponent* AOwner);

__fastcall TDBCheckBox(HWND ParentWindow) : Stdctrls::TCustomCheckBox(ParentWindow) { }

Description

Call TDBCheckBox indirectly, using the new keyword, to create a DB checkbox at runtime. For TDBCheckBox objects placed on forms or data modules at design time, TDBCheckBox is called automatically.

Pass a single Component as a parameter to provide the TDBCheckBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the DB check box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor to allocate and initialize a generic checkbox, TDBCheckBox

•	Adds csReplicatable to ControlStyle.

•	Creates and initializes the helper objects needed to link to a dataset.


TDBCheckBox::~TDBCheckBox

TDBCheckBox	See also

Destroys an instance of TDBCheckBox.

__fastcall virtual ~TDBCheckBox(void);

Description

Do not call ~TDBCheckBox directly in an application. Instead, use delete.

~TDBCheckBox frees the helper objects of the TDBCheckBox before calling the parent object's destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TButtonControl

TCustomCheckBox


 TDBComboBox

Hierarchy	Properties	Methods	Events	See also

TDBComboBox represents a data-aware combo box control.

Unit

dbctrls

Description

Use TDBComboBox to allow the user to change the value of a field on the current record in a dataset either by selecting an item from a list or by typing in the edit box part of the control. The selected item or entered text becomes the new value of the field if the database combo box’s ReadOnly property is false. The combo box can be customized to enable or disable typing in the edit region of the control, to display the list as a drop down or as a permanently displayed list, to sort the items in the list, and so on.


TDBComboBox properties

TDBComboBox	Alphabetically	Legend

In TDBComboBox

DataField

DataSource

Field

Items

ReadOnly

Style

Derived from TCustomComboBox

Canvas

CharCase

DropDownCount

DroppedDown

ItemHeight

ItemIndex

SelLength

SelStart

SelText

Sorted

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBComboBox properties

TDBComboBox	By object	Legend

Align

BoundsRect

Brush

Canvas

CharCase

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

DropDownCount

DroppedDown

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

ItemHeight

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

SelLength

SelStart

SelText

ShowHint

Showing

Sorted

Style

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TDBComboBox::DataField

TDBComboBox	See also

Identifies the field from which the combo box displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Set DataField to specify which field is represented by the combo box. The combo box displays the current value of this field, and allows the user to set the value of this field on the current record. The dataset the field is located in is specified by the DataSource property.


TDBComboBox::DataSource

TDBComboBox	See also

Links the combo box to a dataset.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Specify the data source component that identifies the dataset in which the data is found. To allow the combo box to represent the data for a field, both the DataSource and the DataField properties must be set.


TDBComboBox::Field

TDBComboBox	See also

Identifies the TField object whose current value the combo box represents.

__property Db::TField* Field = {read=GetField};

Description

Use the Field object to change the value of the data in the field programmatically.


TDBComboBox::Items

TDBComboBox	See also

Contains the strings that appear in the list of the database combo box.

__property Items  = {write=SetItems};

Description

Use Items to specify the values the user can choose from. Because Items is an object of type TStrings, you can add, delete, insert, and move items using the Add, Delete, Insert, Exchange, and Move methods of the TStrings object. For example, to add each string to the combo box list, write a line of code such as the following:

The ItemIndex property determines which item is selected, if any.


TDBComboBox::ReadOnly

TDBComboBox	See also

Determines if the user can change the value of the field.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Set ReadOnly to specify whether the combo box should be used for display purposes only. If ReadOnly is true, the combo box can only be used to display the value of the field on the current record. If ReadOnly is false, the user can use the combo box to edit the field’s value.


TDBComboBox::Style

TDBComboBox	See also

Determines how the combo box displays its items.

__property Style;

Description

Use Style to specify whether the user can type values into the edit region as well as select values from the list, whether the list drops down when the user clicks a button or if it is always displayed, and so on. By default, Style is csDropDown, meaning that the combo box displays each item as a string in a drop-down list, and that users can edit the value in the edit region. Style can be any of the following values:

Value	Meaning

csDropDown	Creates a drop-down list with an edit box in which the user can enter values. All items are strings that represent the contents of the field on the current record, each item having the same height.

csSimple	Creates an edit box with a fixed list (list box) underneath. The length of the list is determined by the Height of the combo box. The user can change the contents of the field by typing in a new value or selecting a value from the list.

csDropDownList	Creates a drop-down list with an attached static text box. All items are the same height. The edit box is blank unless the current contents of the field matches one of the specified Items in the drop-down list. The user can change the contents of the field only by selecting one of the strings in the drop-down list.

csOwnerDrawFixed	Same as csDropDownList except that items are not drawn automatically. Items have the height specified by the ItemHeight property.

csOwnerDrawVariable	Same as csDropDownList except that items are not drawn automatically. Items can vary in height.

Owner-draw combo boxes can display items other than strings. For example, a combo box could display graphical images along with or instead of its strings. Owner-draw combo boxes require more programming, however, as the application must render the image for each item in the list.

When Style is csOwnerDrawFixed or csOwnerDrawVariable, the OnDrawItem event occurs when the list items need to be drawn. If Style is csOwnerDrawVariable, an OnMeasureItem event occurs as well.


TDBComboBox events

TDBComboBox	Alphabetically	Legend

Derived from TCustomComboBox

OnChange

OnDrawItem

OnDropDown

OnMeasureItem

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDBComboBox events

TDBComboBox	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDrawItem

OnDropDown

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMeasureItem

OnStartDrag


TDBComboBox methods

TDBComboBox	Alphabetically

In TDBComboBox

~TDBComboBox

TDBComboBox

Derived from TCustomComboBox

Clear

SelectAll

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBComboBox methods

TDBComboBox	By object

~TDBComboBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBComboBox

Update

UpdateControlState


TDBComboBox::TDBComboBox

TDBComboBox	See also

Creates an instance of TDBComboBox.

__fastcall virtual TDBComboBox(Classes::TComponent* AOwner);

__fastcall TDBComboBox(HWND ParentWindow) : Stdctrls::TCustomComboBox(ParentWindow) { }

Description

Call TDBComboBox indirectly, using the new keyword, to create a DB combo box at runtime. For TDBComboBox objects placed on forms or data modules at design time, TDBComboBox is called automatically.

Pass a single Component as a parameter to provide the TDBComboBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the DB combo box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor to allocate and initialize a generic combo box object, TDBComboBox creates and initializes the helper objects needed to link to a dataset.


TDBComboBox::~TDBComboBox

TDBComboBox	See also

Destroys an instance of TDBComboBox.

__fastcall virtual ~TDBComboBox(void);

__fastcall TDBComboBox(HWND ParentWindow) : Stdctrls::TCustomComboBox(ParentWindow) { }

Description

Do not call ~TDBComboBox directly in an application. Instead, use delete.

~TDBComboBox frees the helper objects of the TDBComboBox before calling the parent object's destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomComboBox


TDBCtrlPanel

Hierarchy	Properties	Methods	See also

TDBCtrlPanel represents a panel in a TDBCtrlGrid object.

Unit

dbcgrids

Description

Use TDBCtrlPanel to hold the fields from a single record in a dataset.  TDBCtrlGrid represents the records in a dataset by arranging copies of the same TDBCtrlPanel object in rows or columns, where each panel represents a single record in the dataset.

Lay out a single panel at design time.  Add data-aware edit controls or data display objects.  At runtime, TDBCtrlGrid replicates the panel for the records in the dataset.

The appearance of the panel is determined by the properties of the TDBCtrlGrid object that contains the panel.  The OnPaintPanel event of TDBCtrlGrid allows customized painting of the panels.


TDBCtrlPanel properties

TDBCtrlPanel	Alphabetically	Legend

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBCtrlPanel properties

TDBCtrlPanel	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TDBCtrlPanel methods

TDBCtrlPanel	Alphabetically

In TDBCtrlPanel

~TDBCtrlPanel

TDBCtrlPanel

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBCtrlPanel methods

TDBCtrlPanel	By object

~TDBCtrlPanel

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBCtrlPanel

Update

UpdateControlState


TDBCtrlPanel::TDBCtrlPanel

TDBCtrlPanel 	See also

TDBCtrlPanel creates a new TDBCtrlPanel object.

__fastcall virtual TDBCtrlPanel(Classes::TComponent* AOwner) : Controls::TWinControl(AOwner) { }

__fastcall TDBCtrlPanel(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

__fastcall TDBCtrlPanel(TDBCtrlGrid* DBCtrlGrid);

Description

Applications should not call the constructor for TDBCtrlPanel directly.  TDBCtrlGrid calls the constructor that takes a TDBCtrlGrid as an argument (listed third) from its own constructor.

Component writers may need to explicitly invoke a constructor from descendants of TDBCtrlGrid. When doing so, use the new keyword, rather than calling the constructor directly. When invoking the constructor, pass a DBCtrlGrid as the single argument in order to obtain the third constructor. This constructor initializes the Parent property to the DBCtrlGrid parameter and initializes the ControlStyle property to include csAcceptsControls, csCaptureMouse, csClickEvents, csDoubleClicks, csOpaque, and csReplicatable.

The other two constructors are unlikely to be used. They create a DBCtrlGridPanel without any relationship to a TDBCtrlGrid. The first passes an Owner parameter that is responsible for freeing the instance. The second embeds the DBCtrlGridPanel in the non-VCL window passed as the ParentWindow parameter.


TDBCtrlPanel::~TDBCtrlPanel

TDBCtrlPanel

~TDBCtrlPanel frees the memory associated with the TDBCtrlPanel object.

__fastcall virtual ~TDBCtrlPanel(void) { }

Description

Do not call ~TDBCtrlPanel directly. Instead, use the delete keyword on the object, which causes ~TDBCtrlPanel to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


 TDBCtrlGrid

Hierarchy	Properties	Methods	Events	See also

TDBCtrlGrid displays records from a data source in a free-form layout.

Unit

dbcgrids

Description

Put a TDBCtrlGrid object on a form to display and edit the records from a database table or query. Unlike the TDBGrid object, which displays each record in a single row, TDBCtrlGrid allows a free-form layout for each record in the dataset. Each record is displayed in its own panel; Design one panel at design time and TDBCtrlGrid replicates that panel for each record displayed.

At runtime, users can use the database navigator (TDBNavigator) to move through data in the TDBCtrlGrid object, and to insert, delete, and edit the data. Edits made using the data grid are not posted to the underlying dataset until the user moves to a different record or closes the application.


TDBCtrlGrid properties

TDBCtrlGrid	Alphabetically	Legend

In TDBCtrlGrid

AllowDelete

AllowInsert

Canvas

ColCount

DataSource

EditMode

Orientation

PanelBorder

PanelCount

PanelHeight

PanelIndex

PanelWidth

RowCount

SelectedColor

ShowFocus

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBCtrlGrid properties

TDBCtrlGrid	By object	Legend

Align

AllowDelete

AllowInsert

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ColCount

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DataSource

DesignInfo

DragCursor

DragMode

EditMode

Enabled

Font

Handle

Height

HelpContext

Hint

Left

Name

Orientation

Owner

PanelBorder

PanelCount

PanelHeight

PanelIndex

PanelWidth

Parent

ParentColor

ParentFont

ParentShowHint

ParentWindow

PopupMenu

RowCount

SelectedColor

ShowFocus

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TDBCtrlGrid::AllowDelete

TDBCtrlGrid	See also

Determines whether the user can delete the current record from the dataset by pressing Ctrl+Delete.

__property bool AllowDelete = {read=FAllowDelete, write=FAllowDelete, default=1};

Description

Set AllowDelete to false to prevent the TDBCtrlGrid object from deleting records.

When AllowDelete is false, TDBCtrlGrid won’t delete records from the dataset when the user presses Ctrl+Delete or the DoKey method is called with the Key parameter set to gkDelete. The TDBCtrlGrid object can still be used to insert records.

When AllowDelete is true (the default), TDBCtrlGrid will delete the current record when the user presses Ctrl+Delete or when the DoKey method is called with the Key parameter set to gkDelete. Even with AllowDelete set to true, records can’t be deleted unless the dataset is in edit mode.


TDBCtrlGrid::AllowInsert

TDBCtrlGrid	See also

Determines whether the user can insert new records with the Insert key or append new records with the Ctrl+Insert key combination.

__property bool AllowInsert = {read=FAllowInsert, write=FAllowInsert, default=1};

Description

Set AllowInsert to false to prevent the TDBCtrlGrid object from inserting records.

When AllowInsert is false, TDBCtrlGrid won’t insert records into the dataset when the user presses Insert or Ctrl+Insert or when the DoKey method is called with the Key parameter set to gkInsert or gkAppend. The TDBCtrlGrid object can still be used to delete records.

When AllowInsert is true (the default), TDBCtrlGrid will insert a new record into the dataset before the current record when the user presses Insert or append a new record to the end of the dataset when the user presses Ctrl+Insert. Even with AllowInsert set to true, records can’t be inserted unless the dataset is in edit mode.


TDBCtrlGrid::Canvas

TDBCtrlGrid	See also

Indicates the drawing surface used to draw the TDBCtrlGridObject.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

Use the properties and methods of Canvas to draw an image of a panel in the TDBCtrlGrid object from an OnPaintPanel event handler.


TDBCtrlGrid::ColCount

TDBCtrlGrid	See also

Specifies the number of columns of panels shown in the grid.

__property int ColCount = {read=FColCount, write=SetColCount, nodefault};

Description

Set ColCount to the number of columns of panels that should appear in the TDBCtrlGrid object. Each panel represents a separate record in the dataset.

Setting ColCount causes the TDBCtrlGrid object to resize to accomodate the new number of columns. PanelWidth doesn’t change.


TDBCtrlGrid::DataSource

TDBCtrlGrid

Identifies the link to the dataset where the TDBCtrlGrid object finds its data.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Set DataSource to the TDataSource object that links to the dataset where the grid should fetch its data. DataSource allows the data-aware grid to read from, write to, and navigate around the dataset.


TDBCtrlGrid::EditMode

TDBCtrlGrid	See also

Determines whether the TDBCtrlGrid can be used to insert, delete, or edit records.

__property bool EditMode = {read=GetEditMode, write=SetEditMode, nodefault};

Description

Set EditMode to true to allow the user to edit the dataset using the grid. The user can toggle EditMode by pressing F2 or Enter. Inserting or deleting records using the grid will set EditMode to true.


TDBCtrlGrid::Orientation

TDBCtrlGrid	See also

Determines the order in which records from the dataset are displayed in the TDBCtrlGrid.

enum TDBCtrlGridOrientation { goVertical, goHorizontal };

__property TDBCtrlGridOrientation Orientation = {read=FOrientation, write=SetOrientation, default=0};

Description

Set Orientation to goVertical (the default) to have the panels ordered in rows with a vertical scroll bar. Set Orientation to goHorizontal to arrange panels in columns with a horizontal scroll bar.


TDBCtrlGrid::PanelBorder

TDBCtrlGrid	See also

Determines whether each panel is drawn with a raised border around it.

enum TDBCtrlGridBorder { gbNone, gbRaised };

__property TDBCtrlGridBorder PanelBorder = {read=FPanelBorder, write=SetPanelBorder, default=1};

Description

The default value of gbRaised draws a raised border. Set PanelBorder to gbNone to eliminate the border.


TDBCtrlGrid::PanelCount

TDBCtrlGrid	See also

Specifies the number of records visible in the grid.

__property int PanelCount = {read=FPanelCount, nodefault};

Description

TDBCtrlGrid can represent up to ColCount * RowCount panels. Usually, PanelCount will be this value. PanelCount will be smaller than this if there are not enough records in the dataset to fill the entire grid.


TDBCtrlGrid::PanelHeight

TDBCtrlGrid	See also

Specifies the height (in pixels) of each panel.

__property int PanelHeight = {read=FPanelHeight, write=SetPanelHeight, nodefault};

Description

Set PanelHeight to the desired size of each panel in the grid. When the PanelHeight property is set, the grid resizes itself to fit the new panel height.


TDBCtrlGrid::PanelIndex

TDBCtrlGrid	See also

Specifies the index of the panel in the grid which represents the current record.

__property int PanelIndex = {read=FPanelIndex, write=SetPanelIndex, nodefault};

Description

Read PanelIndex to determine which panel represents the current record in the dataset. Set PanelIndex to move in the dataset to the record corresponding to a panel in the grid.

PanelIndex is a number in the range 0...PanelCount - 1, where 0 is the first panel, 1 is the second panel, and so on. The location of the panel with the index PanelIndex depends on the value of the Orientation property. When Orientation is goVertical, the panels are counted by rows. When Orientation is goHorizontal, the panels are counted by columns.


TDBCtrlGrid::PanelWidth

TDBCtrlGrid	See also

Specifies the width (in pixels) of each panel.

__property int PanelWidth = {read=FPanelWidth, write=SetPanelWidth, nodefault};

Description

Set PanelWidth to the desired size of each panel in the grid. When the PanelWidth property is set, the grid resizes itself to fit the new panel width.


TDBCtrlGrid::RowCount

TDBCtrlGrid	See also

Specifies the number of rows of panels displayed in the grid.

__property int RowCount = {read=FRowCount, write=SetRowCount, nodefault};

Description

Set RowCount to the number of rows of panels that should appear in the TDBCtrlGrid object. Each panel represents a separate record in the dataset.

Setting RowCount causes the TDBCtrlGrid object to resize to accomodate the new number of rows. PanelHeight doesn’t change.


TDBCtrlGrid::ShowFocus

TDBCtrlGrid	See also

Indicates whether to draw a focus rectangle around the current record in the TDBCtrlGrid when it has input focus.

__property bool ShowFocus = {read=FShowFocus, write=FShowFocus, default=1};

Description

Set ShowFocus to true to have TDBCtrlGrid draw a focus rectangle around the current record when it has input focus. Set ShowFocus to false when providing visual feedback of focus in some other manner in an OnPaintPanel event handler.


TDBCtrlGrid::SelectedColor

TDBCtrlGrid 	See also

Specifies the background color of the panel that represents the current record in the dataset.

__property Graphics::TColor SelectedColor = {read=FSelectedColor, write=SetSelectedColor, stored=FSelColorChanged, default=-2147483643};

Description

Set SelectedColor to a value other than value of the Color property to make the panel that represents the current record stand out. TDBCtrlGrid draws the selected panel using SelectedColor even when it does not have input focus. All other panels are drawn with the background set to the value of the Color property.


TDBCtrlGrid events

TDBCtrlGrid	Alphabetically	Legend

In TDBCtrlGrid

OnPaintPanel

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBCtrlGrid events

TDBCtrlGrid	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaintPanel

OnStartDrag


TDBCtrlGrid::OnPaintPanel

TDBCtrlGrid	See also

Occurs when TDBCtrlGrid needs to draw a panel in the grid.

typedef void __fastcall (__closure *TPaintPanelEvent)(TDBCtrlGrid* DBCtrlGrid, int Index);

__property TPaintPanelEvent OnPaintPanel = {read=FOnPaintPanel, write=FOnPaintPanel};

Description

Write an OnPaintPanel event handler to customize the drawing of a panel in the TDBCtrlGrid object. TDBCtrlGrid paints the background using the Color or SelectedColor property, including the raised border if it is specified by the PanelBorder property. Then the OnPaintPanel event occurs to allow an event handler to add to the image of the panel.

The DBCtrlGrid parameter is the grid that contains the panel. The Index parameter is the index of the panel being painted, where 0 is the first panel, 1 is the second panel, and so on. Use the PanelIndex property to determine whether the panel being drawn is selected.

Use the Canvas property to paint the panel. The point (0,0) on the canvas is the upper left corner of the panel, and the point (PanelWidth, PanelHeight) is the lower right corner.

Controls placed on the panel are drawn separately and do not need to be drawn in an OnPaintPanel event handler.


TDBCtrlGrid methods

TDBCtrlGrid	Alphabetically

In TDBCtrlGrid

~TDBCtrlGrid

DoKey

GetTabOrderList

KeyDown

TDBCtrlGrid

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBCtrlGrid methods

TDBCtrlGrid	By object

~TDBCtrlGrid

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DoKey

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBCtrlGrid

Update

UpdateControlState


TDBCtrlGrid::TDBCtrlGrid

TDBCtrlGrid	See also

Creates and initializes an instance of TDBCtrlGrid.

__fastcall virtual TDBCtrlGrid(Classes::TComponent* AOwner);

__fastcall TDBCtrlPanel(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not call TDBCtrlGrid directly when creating a TDBCtrlGrid object at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TDBCtrlGrid object. TDBCtrlGrid objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TDBCtrlGrid object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TDBCtrlGrid object in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TDBCtrlGrid allocates the helper objects it uses and initializes

•	AllowInsert and AllowDelete to true.

•	ColCount to 1 and RowCount to 3.

•	ControlStyle to include csOpaque, csDoubleClicks.

•	PanelBorder to gbRaised.

•	PanelWidth to 200 and PanelHeight to 72.

•	SelectedColor to Color.

•	ShowFocus to true.

•	TabStop to true.


TDBCtrlGrid::~TDBCtrlGrid

TDBCtrlGrid	See also

Destroys an instance of TDBCtrlGrid.

__fastcall virtual ~TDBCtrlGrid(void);

Description

Do not call ~TDBCtrlGrid directly in an application. Instead, use the delete keyword, which takes an indirect reference to the TDBCtrlGrid object.

~TDBCtrlGrid frees the helper objects used by TDBCtrlGrid before calling the parent object's destructor.


TDBCtrlGrid::DoKey

TDBCtrlGrid 	See also

Implements the responses to a number of standard keystrokes.

void __fastcall DoKey(TDBCtrlGridKey Key);

Description

Call DoKey to perform the operation specified by the Key parameter. For example, use DoKey to remap keystrokes from an OnKeyDown event handler.

The actions performed for the different values of Key are given in the following table

Value	Action

gkNull	Do nothing.

gkEditMode	Toggle the EditMode property.

gkPriorTab	Move to the previous panel.

gkNextTab	Move to the next panel.

gkLeft	Move one panel to the left.

gkRight	Move one panel to the right.

gkUp	Move one panel up.

gkDown	Move one panel down.

gkScrollUp	Move one panel up.

gkScrollDown	Move one panel down.

gkPageUp	Move ColCount * RowCount records up in the dataset.

gkPageDown	Move ColCount * RowCount records down in the dataset.

gkHome	Move to the first record in the dataset.

gkEnd	Move to the last record in the dataset.

gkInsert	Insert a new record prior to the current record in the dataset and set EditMode to true.

gkAppend	Insert a new record at the end of the dataset and set EditMode to true.

gkDelete	Delete the current record from the dataset and set EditMode to false.

gkCancel	Cancel any edits not written to the dataset and set EditMode to false.


TDBCtrlGrid::GetTabOrderList

TDBCtrlGrid	See also

Overrides the default to remove all child controls from the tab order.

DYNAMIC void __fastcall GetTabOrderList(Classes::TList* List);

Description

GetTabOrderList returns an empty list. TDBCtrlGrid implements its own handling of the tab key to move through the panels in database order.


TDBCtrlGrid::KeyDown

TDBCtrlGrid 	See also

Performs special processing when a key is pressed.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

After calling the OnKeyDown event handler, KeyDown translates each combination of the Key and Shift parameters into a logical key code and calls the DoKey method to perform the appropriate action.

KeyDown performs the following translations:

Key and Shift values	Key code

LeftArrow	gkLeft

RightArrow	gkRight

UpArrow	gkUp

DownArrow	gkDown

PageUp	gkPageUp

PageDown	gkPageDown

Home	gkHome

End	gkEnd

Return	gkEditMode

F2	gkEditMode

Insert	gkAppend

Ctrl+Insert	gkInsert

Ctrl+Delete	gkDelete

Escape	gkCancel

All other keys	gkNull


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TDBCtrlGridLink

Hierarchy	Properties	Methods	See also

TDBCtrlGridLink helps manage data events for a TDBCtrlGrid object.

Unit

dbcgrids

Description

TDBCtrlGridLink is tailored to work with a TDBCtrlGrid. It should only be used by the TDBCtrlGrid class.


TDBCtrlGridLink properties

TDBCtrlGridLink	Alphabetically	Legend

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TDBCtrlGridLink properties

TDBCtrlGridLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TDBCtrlGridLink methods

TDBCtrlGridLink	Alphabetically	Legend

In TDBCtrlGridLink

~TDBCtrlGridLink

ActiveChanged

DataSetChanged

TDBCtrlGridLink

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDBCtrlGridLink methods

TDBCtrlGridLink	By object	Legend

~TDBCtrlGridLink

ActiveChanged

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DataSetChanged

DefaultHandler

Dispatch

Edit

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDBCtrlGridLink

UpdateRecord


TDBCtrlGridLink::ActiveChanged

TDBCtrlGridLink	See also

Informs the TDBCtrlGrid object of changes in the Active property.

virtual void __fastcall ActiveChanged(void);

Description

Applications can’t call the ActiveChanged procedure directly. Changes in the Active property trigger this procedure. ActiveChanged causes the TDBCtrlGrid object to update its appearance to reflect the data in the dataset.


TDBCtrlGridLink::TDBCtrlGridLink

TDBCtrlGridLink	See also

Creates an instance of TDBCtrlGridLink.

__fastcall TDBCtrlGridLink(TDBCtrlGrid* DBCtrlGrid);

Description

Applications should not call the constructor for a TDBCtrlGridLink directly. The TDBCtrlGrid that owns a TDBCtrlGridLink instantiates the TDBCtrlGridLink from its own constructor.


TDBCtrlGridLink::DataSetChanged

TDBCtrlGridLink	See also

Informs the TDBCtrlGrid of changes to the dataset.

virtual void __fastcall DataSetChanged(void);

Description

Applications can’t call the DataSetChanged method directly. DataSetChanged is called automatically when the contents of the dataset change. When the dataset scrolls or when the representation of the dataset by the TDBCtrlGrid changes, DataSetChanged is called indirectly. DataSetChanged causes the TDBCtrlGrid object to update its appearance to reflect the changes to the dataset.


Accessibility

Read-only


TDBCtrlGridLink::~TDBCtrlGridLink

TDBCtrlGridLink

Frees the memory associated with the TDBCtrlGridLink object.

__fastcall virtual ~TDBCtrlGridLink(void) { }

Description

Do not call ~TDBCtrlGridLink directly. Instead, use the delete keyword on the object, which causes ~TDBCtrlGridLink to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


TDBDataSet

Hierarchy	Properties	Methods	Events	See also

TDBDataSet encapsulates database connectivity for descendent dataset objects.

Unit

dbtables

Description

TDBDataSet is a dataset object that defines database-related connectivity properties and methods for a dataset. Applications never use TDBDataSet objects directly. Instead they use the descendants of TDBDataSet, such as TQuery, TStoredProc, and TTable, which inherit its database-related properties and methods.

Developers who create custom dataset components may want to derive them from TDBDataSet to inherit all the functionality of TDataSet and the BDE-related properties and methods of TBDEDataSet in addition to the database-specific properties of TDBDataSet. In this case, developers should examine the source code to study the protected methods of TDBDataSet that are not documented for this object.


TDBDataSet properties

TDBDataSet	Alphabetically	Legend

In TDBDataSet

Database

DatabaseName

DBHandle

DBLocale

DBSession

Provider

SessionName

UpdateMode

Derived from TBDEDataSet

CacheBlobs

CachedUpdates

CanModify

ExpIndex

Filter

Filtered

FilterOptions

Handle

KeySize

Locale

RecNo

RecordCount

RecordSize

UpdateObject

UpdateRecordTypes

UpdatesPending

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

DataSource

DefaultFields

Designer

EOF

FieldCount

FieldDefs

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBDataSet properties

TDBDataSet	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CacheBlobs

CachedUpdates

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Database

DatabaseName

DataSource

DBHandle

DBLocale

DBSession

DefaultFields

Designer

DesignInfo

EOF

ExpIndex

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Handle

KeySize

Locale

Modified

Name

Owner

Provider

RecNo

RecordCount

RecordSize

SessionName

State

Tag

UpdateMode

UpdateObject

UpdateRecordTypes

UpdatesPending

VCLComObject


TDBDataSet::Database

TDBDataSet	See also 	Example

Identifies the database component for which this dataset represents one or more tables.

__property TDatabase* Database = {read=FDatabase};

Description

Use Database to access the properties, events, and methods of the database component associated with this dataset. Database is a read-only property that is automatically set when the database specified by the DatabaseName property is opened.


TDBDataSet::DatabaseName

TDBDataSet	See also 	Example

Specifies the name of the database to associate with this dataset.

__property System::AnsiString DatabaseName = {read=FDatabaseName, write=SetDatabaseName};

Description

Use DatabaseName to specify the name of the database to associate with this dataset component. DatabaseName should match the name of a database component used in the application.

Note:	Attempting to set DatabaseName when a database already associated with this component is open raises an exception.

Tip:	At design time double-click a TDatabase component to invoke the Database editor and set the DatabaseName.


TDBDataSet::DBHandle

TDBDataSet	See also 	Example

Specifies the Borland Database Engine (BDE) database handle for the dataset.

__property Bde::hDBIDb DBHandle = {read=GetDBHandle};

Description

Check DBHandle to determine the database handle for the dataset. DBHandle is only useful in applications that bypass database and dataset methods to write directly to the BDE API. Many BDE function calls require a handle parameter. DBHandle is assigned an initial value when a session is activated.

Note:	Do not use this property unless an application requires BDE functionality not available through standard C++Builder components.


TDBDataSet::DBLocale

TDBDataSet	See also

Identifies the Borland Database Engine (BDE) language driver for the dataset component.

__property void * DBLocale = {read=GetDBLocale};

Description

Examine DBLocale to determine the BDE language driver used by the database component associated with which this dataset is associated. Applications that make direct calls to the BDE may need to pass DBLocale information as an API function parameter.

Note:	Do not use this property unless an application requires BDE functionality not available through standard data access components.


TDBDataSet::DBSession

TDBDataSet	See also

Points to the database session component associated with this dataset.

__property TSession* DBSession = {read=GetDBSession};

Description

Use DBSession to determine the session component that controls the database component with which this dataset component is associated. By default, a database component is associated with the default session component, Session, that is automatically created for all database applications.


TDBDataSet::Provider

TDBDataSet	See also

Identifies the provider interface for this dataset.

__property Stdvcl::_di_IProvider Provider = {read=GetProvider};

Description

Check Provider to determine the IProvider interface for this object. The IProvider interface is only of interest to developers of multi-tiered applications who wish to enable client datasets to communicate directly with this dataset object on the application server through the IProvider interface.


TDBDataSet::SessionName

TDBDataSet	See also

Identifies the name of the session with which this dataset is associated.

__property System::AnsiString SessionName = {read=FSessionName, write=SetSessionName};

Description

Use SessionName to determine or specify the session with which a dataset component is associated. SessionName is automatically set to the name of the SessionName property of the database component with which a dataset component is associated. If SessionName is blank, a dataset component is automatically associated with the default session, Session.

To associate a dataset component with a different session SessionName must matches the SessionName property of an existing session component that is also used by the database component with which this dataset is associated.


TDBDataSet::UpdateMode

TDBDataSet	See also	Example

Determines how the Borland Database Engine (BDE) finds records being updated in an SQL database.

enum TUpdateMode { upWhereAll, upWhereChanged, upWhereKeyOnly };

__property TUpdateMode UpdateMode = {read=FUpdateMode, write=SetUpdateMode, default=0};

Description

Use UpdateMode to specify the criteria to use when locating a record in the dataset. UpdateMode can take one of the following values:

Value	Meaning

upWhereAll	All columns (fields) are used to locate the record.

upWhereChanged	Only the key fields and fields that have changed are used to find the record.

upWhereOnly	Only the key fields are used to find the record.


TDBDataSet events

TDBDataSet	Alphabetically	Legend

Derived from TBDEDataSet

OnServerYield

OnUpdateError

OnUpdateRecord

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TDBDataSet events

TDBDataSet	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnServerYield

OnUpdateError

OnUpdateRecord


TDBDataSet methods

TDBDataSet	Alphabetically

In TDBDataSet

~TDBDataSet

CheckOpen

CloseDatabase

OpenDatabase

TDBDataSet

Derived from TBDEDataSet

ApplyUpdates

BookmarkValid

Cancel

CancelUpdates

CommitUpdates

CompareBookmarks

FetchAll

GetCurrentRecord

GetIndexInfo

Locate

Lookup

RevertRecord

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Post

Prior

Refresh

Resync

SetFields

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBDataSet methods

TDBDataSet	By object

~TDBDataSet

ActiveBuffer

Append

AppendRecord

ApplyUpdates

Assign

BookmarkValid

Cancel

CancelUpdates

CheckBrowseMode

CheckOpen

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CommitUpdates

CompareBookmarks

ControlsDisabled

CursorPosChanged

DefaultHandler

Delete

DestroyComponents

Destroying

DisableControls

Dispatch

Edit

EnableControls

FetchAll

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindLast

FindNext

FindPrior

First

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GotoBookmark

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

Last

Locate

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

Post

Prior

Refresh

RemoveComponent

Resync

RevertRecord

SafeCallException

SetFields

TDBDataSet

Translate

UpdateCursorPos

UpdateRecord

UpdateStatus


TDBDataSet::CheckOpen

TDBDataSet	See also

Checks the result of a call to the Borland Database Engine (BDE).

bool __fastcall CheckOpen(Word Status);

Description

Call CheckOpen to determine if a call to the BDE returns an error when an attempt is made to access a table. Status is the return result of a previous call to the BDE. CheckOpen returns true if there is access is successful. If Status indicates insufficient table rights when accessing a Paradox table, CheckOpen calls the database session’s GetPassword method to prompt the user for a password. If the dialog is successful, CheckOpen returns true.

Otherwise CheckOpen returns false, indicating that dataset access failed.


TDBDataSet::CloseDatabase

TDBDataSet	See also

Closes a database connection associated with the database session.

void __fastcall CloseDatabase(TDatabase* Database);

Description

Call CloseDatabase to close a persistent database connection, or to close and free a temporary database connection. Database specifies the name of the database component for which to close the connection.

CloseDatabase decrements the specified database component’s reference count, and then, if the reference count is zero and the database component’s KeepConnection property is false, CloseDatabase either frees a temporary database component or closes the connection for a persistent database component.

Note:	Calling CloseDatabase for a persistent database component does not close the connection. To close a connection for a persistent database component, call the database component’s Close method directly.

Temporary database components are closed automatically when the last dataset associated with the database component is closed, but an application can call CloseDatabase prior to that time to force closure. Closing a connection established by a temporary database component does not free the component if the session’s KeepConnections property is true (the default). To free temporary database components after closing their connections call DropConnections method of the session.


TDBDataSet::OpenDatabase

TDBDataSet	See also

Opens the database that contains the dataset.

TDatabase* __fastcall OpenDatabase(void);

Description

Call OpenDatabase to connect to the database that contains the dataset, or to create a temporary database component and connect to a database. The DatabaseName property specifies the database to open.

OpenDatabase makes the current session active, then determines whether the DatabaseName property corresponds to the DatabaseName property of an existing database component. If it does not, OpenDatabase creates a temporary database component, assigning the DatabaseName parameter to the DatabaseName property. Finally, OpenDatabase calls the Open method of the database to connect to a database server, then increments the session’s database reference count by one.


TDBDataSet::TDBDataSet

TDBDataSet

TDBDataSet creates a new TDBDataSet object.

__fastcall virtual TDBDataSet(Classes::TComponent* AOwner) : Dbtables::TBDEDataSet(AOwner) { }

Description

Call TDBDataSet to instantiate a dataset component at runtime. Ordinarily applications instantiate TBDEDataSet descendants, such as TTable, TQuery, or TStoredProc, and these instantiated objects are automatically handled by C++Builder.

In some cases, a database application may have a need to create an instance of a TBDEDataSet at runtime. TDBDataSet:

•	Calls its inherited constructor.

•	Set the Locale property of the dataset to the locale of the default session.

•	Sets the CacheBlobs property to True.


TDBDataSet::~TDBDataSet

TDBDataSet	See also

~TDBDataSet frees the memory associated with the TDBDataSet object.

__fastcall virtual ~TDBDataSet(void) { }

Description

Do not call ~TDBDataSet directly. Instead, use the delete keyword on the object, which causes ~TDBDataSet to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet

TBDEDataSet


 TDBEdit

Hierarchy	Properties	Methods	Events	See also

TDBEdit represents a single-line edit control that can display and edit a field in a dataset.

Unit

dbctrls

Description

Use TDBEdit to enable users to edit a database field. TDBEdit can use a mask to restrict input to data that is valid for the database field. TDBEdit uses the Text property to represent the contents of the field.

TDBEdit permits only a single line of text. If the field may contain lengthy data that would require multiple lines, consider using a TDBMemo object.

If the application doesn’t require the data-aware capabilities of TDBEdit, use an edit control (TEdit) or a masked edit control (TMaskEdit) instead, to conserve system resources.


TDBEdit properties

TDBEdit	Alphabetically	Legend

In TDBEdit

DataField

DataSource

Field

ReadOnly

Derived from TCustomMaskEdit

EditText

IsMasked

MaxLength

Text

Derived from TCustomEdit

AutoSelect

AutoSize

BorderStyle

CanUndo

CharCase

Modified

PasswordChar

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBEdit properties

TDBEdit	By object	Legend

Align

AutoSelect

AutoSize

BorderStyle

BoundsRect

Brush

CanUndo

CharCase

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

EditText

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IsMasked

Left

MaxLength

Modified

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PasswordChar

PopupMenu

ReadOnly

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TDBEdit::DataField

TDBEdit	See also

Specifies the field from which the edit control displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Use DataField to bind the edit control to a field in the dataset. To fully specify a database field, both the dataset and the field within that dataset must be defined. The DataSource property of the edit box control specifies the dataset which contains the DataField.

If the DataField refers to a database field that contains integer or floating-point data, only characters that are valid in such a field can be entered in the edit box. Characters that are not legal are not accepted.


TDBEdit::DataSource

TDBEdit	See also

Links the edit control to the dataset that contains the field it represents.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use DataSource to link the edit control to a dataset in which the data can be found. To fully specify a database field for the edit control, both the dataset and a field within that dataset must be defined. Use the DataField property to specify the particular field within the dataset.


TDBEdit::Field

TDBEdit	See also

Specifies the TField object for the database field the edit box represents.

__property Db::TField* Field = {read=GetField};

Description

Read Field to get direct access to the contents and properties of the database field without going through the edit window. Use Field to change the contents of the database field programmatically. Use the Text property instead if you want to change the contents of the edit window without immediately posting the changes to the dataset. Changing the Text property allows the user to cancel the changes.


TDBEdit::ReadOnly

TDBEdit	See also

Determines whether the user can use the database edit box to change the value of the field in the current record.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Set ReadOnly to true to prevent the user from changing the contents of the database field. When ReadOnly is true, the edit control is used only to display the contents of the field. If ReadOnly is false, the user can change the field's value as long as the dataset is in edit mode.


TDBEdit events

TDBEdit	Alphabetically	Legend

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBEdit events

TDBEdit	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBEdit methods

TDBEdit	Alphabetically	Legend

In TDBEdit

~TDBEdit

Change

EditCanModify

KeyDown

KeyPress

Notification

Reset

TDBEdit

Derived from TCustomMaskEdit

Clear

GetTextLen

ValidateEdit

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBEdit methods

TDBEdit	By object	Legend

~TDBEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EditCanModify

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

KeyPress

MethodAddress

MethodName

NewInstance

Notification

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

Reset

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TDBEdit

Undo

Update

UpdateControlState

ValidateEdit


TDBEdit::Change

TDBEdit	See also

Responds when the text is modified.

DYNAMIC void __fastcall Change(void);

Description

Applications cannot call this protected method directly. It is triggered automatically by Windows’ events.

Change responds to changes in the text by internally keeping track of the fact that the text has been modified. This information can then be used to know whether there are any changes to post to the dataset or to remove if the user requests a reset.

Additionally, Change calls the inherited method which generates an OnChange event.


TDBEdit::TDBEdit

TDBEdit	See also

Creates an instance of TDBEdit.

__fastcall virtual TDBEdit(Classes::TComponent* AOwner);

__fastcall TDBEdit(HWND ParentWindow) : Mask::TCustomMaskEdit(ParentWindow) { }

Description

Do not call TDBEdit directly when creating a TDBEdit control at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TDBEdit object. TDBEdit objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TDBEdit object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TDBEdit object in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TDBEdit initializes the database handling capabilities of the edit control.


TDBEdit::~TDBEdit

TDBEdit	See also

Destroys an instance of TDBEdit.

__fastcall virtual ~TDBEdit(void);

Description

Do not call ~TDBEdit directly in an application. Instead, use the delete keyword which operates on an indirect reference to a TDBEdit object.

~TDBEdit frees the helper objects that were allocated to manage display issues and database interactions.


TDBEdit::EditCanModify

TDBEdit	See also

Allows or disallows editing of the text depending on whether the dataset is in edit mode.

virtual bool __fastcall EditCanModify(void);

Description

EditCanModify overrides the inherited method so that the control will only allow edits when the dataset is in edit mode. If the edit control should never allow edits, the ReadOnly property should be set.

Note:	EditCanModify is a protected method. Applications cannot call it directly.


TDBEdit::KeyDown

TDBEdit	See also

Supplements the inherited method to drive the dataset into edit mode when the user presses Del or Shift+Insert.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

KeyDown first calls the inherited method, which calls the OnKeyDown event handler. KeyDown next attempts to put the dataset into an editing state when the user types Del or Shift+Insert. Derived classes can override KeyDown to handle additional key combinations, but the inherited method should always be called.

Note:	KeyDown is a protected method. Applications cannot call it directly. It is called automatically in response to Windows events.


TDBEdit::KeyPress

TDBEdit	See also

Supplements the inherited method to handle any keystrokes that alter the state of the edit control.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

KeyPress first calls the inherited method, which calls the OnKeyPress event handler. Next, KeyPress discards the keystroke if it is not a valid character for the field type, or if there is no link to a database field. Valid characters cause KeyPress to attempt to put the dataset into edit mode.

Pressing the Escape key causes KeyPress to call Reset, throwing away all unposted edits.

Note:	KeyPress is a protected method. Applications cannot call it directly. It is called automatically in response to Windows events.


TDBEdit::Notification

TDBEdit	See also

Overrides the inherited method to respond to opRemove notifications on the DataSource.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the inherited method, Notification checks whether the notification indicates the removal of the DataSource. If so, Notification sets the DataSource property to NULL.

Derived classes can override Notification method to handle additional notifications, but the inherited method should be always be called.

Note:	Notification is a protected method. Applications can’t call it directly.


TDBEdit::Reset

TDBEdit	See also

Cancels all unposted edits.

virtual void __fastcall Reset(void);

Description

Reset overrides the default method to cancel all unposted edits to the dataset when the user presses the Escape key.

Note:	Reset is a protected method. Applications cannot call it directly. It is called automatically when the user presses the Escape key.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMaskEdit


TDbEngineErrorDlg

Hierarchy	Properties	Methods	Events	See also

TDbEngineErrorDlg replaces the normal message box for EDBEngineError exceptions thrown at design time.

Unit

Dbexcept

Description

The standard message box displayed by an unhandled exception shows only the exception's name and description. EDBEngineError exceptions, however, contain additional information that can be useful to application developers. For this reason, exceptions of the EDBEngineError class, when thrown at design time, appear in a special dialog box called TDbEngineErrorDlg. The dialog shows the entire stack of BDE errors as represented in the EDBEngineError object.

At runtime, unhandled EDBEngineError exceptions generate the standard message box. But you can use the HookExceptions or ShowException method to display TDbEngineErrorDlg instead. This can be useful for debugging or in cases where you want the end user to have access to BDE error information.


TDbEngineErrorDlg properties

TDbEngineErrorDlg	Alphabetically	Legend

In TDbEngineErrorDlg

DbException

Derived from TCustomForm

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

BorderIcons

BorderStyle

Canvas

ClientHandle

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

FormStyle

HelpFile

Icon

KeyPreview

MDIChildCount

MDIChildren

Menu

ModalResult

ObjectMenuItem

OleFormObject

Parent

PixelsPerInch

Position

PrintScale

Scaled

TileMode

Visible

WindowMenu

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDbEngineErrorDlg properties

TDbEngineErrorDlg	By object	Legend

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

Align

AutoScroll

BorderIcons

BorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHandle

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DbException

Designer

DesignInfo

DropTarget

Enabled

Font

FormStyle

Handle

Height

HelpContext

HelpFile

Hint

HorzScrollBar

Icon

KeyPreview

Left

MDIChildCount

MDIChildren

Menu

ModalResult

Name

ObjectMenuItem

OleFormObject

Owner

Parent

ParentFont

ParentWindow

PixelsPerInch

PopupMenu

Position

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

TileMode

Top

VCLComObject

VertScrollBar

Visible

Width

WindowMenu

WindowProc

WindowState


TDbEngineErrorDlg::DbException

TDbEngineErrorDlg	See also

Holds an instance of EDBEngineError.

__property Dbtables::EDBEngineError* DbException = {read=FDbException, write=FDbException};

Description

DbException is the EDBEngineError instance that causes the error dialog to appear.


TDbEngineErrorDlg events

TDbEngineErrorDlg	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnClose

OnCloseQuery

OnCreate

OnDeactivate

OnDestroy

OnHelp

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TDbEngineErrorDlg events

TDbEngineErrorDlg	By object	Legend

OnActivate

OnClick

OnClose

OnCloseQuery

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHelp

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TDbEngineErrorDlg methods

TDbEngineErrorDlg	Alphabetically

In TDbEngineErrorDlg

~TDbEngineErrorDlg

HookExceptions

ShowException

TDbEngineErrorDlg

Derived from TForm

ArrangeIcons

Cascade

Next

Previous

Tile

Derived from TCustomForm

Close

CloseQuery

DefocusControl

FocusControl

GetFormImage

Hide

Print

Release

SendCancelMode

SetFocus

SetFocusedControl

Show

ShowModal

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDbEngineErrorDlg methods

TDBEngineErrorDlg	By object

~TDbEngineErrorDlg

ArrangeIcons

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Cascade

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

DefaultHandler

DefocusControl

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

HookExceptions

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Next

PaintTo

Perform

Previous

Print

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetFocus

SetFocusedControl

SetTextBuf

Show

ShowException

ShowModal

TDbEngineErrorDlg

Tile

Update

UpdateControlState


TDbEngineErrorDlg::HookExceptions

TDbEngineErrorDlg	See also

Enables the TDbEngineErrorDlg instance, replacing the standard exception message at runtime.

void __fastcall HookExceptions(void);

Description

To display all unhandled EDBEngineError exceptions in a TDbEngineErrorDlg (rather than the standard message box), create a TDbEngineErrorDlg and call HookExceptions to enable it:

TDbEngineErrorDlg *pDBEDlg = new TDbEngineErrorDlg(Application);

pDBEDlg->HookExceptions();

If you include this code in an application's project file, or in the constructor for the project's main form, the TDbEngineErrorDlg will trap and display unhandled EDBEngineError exceptions at runtime.


TDbEngineErrorDlg::ShowException

TDbEngineErrorDlg	See also

Displays an EDBEngineError exception in the TDbEngineErrorDlg.

typedef int TModalResult;

Forms::TModalResult __fastcall ShowException(Dbtables::EDBEngineError* Error);

Description

Call ShowException in an EDBEngineError exception handler to display the exception in a TDbEngineErrorDlg. You can create the TDbEngineErrorDlg in the exception handler itself, or in the initialization section of your application.


TDbEngineErrorDlg::TDbEngineErrorDlg

TDbEngineErrorDlg 	See also

Creates a new TDbEngineErrorDlg object.

__fastcall virtual TDbEngineErrorDlg(Classes::TComponent* AOwner) : Forms::TForm(AOwner) { }

__fastcall TDbEngineErrorDlg(Classes::TComponent* AOwner, int Dummy) :Forms::TForm(AOwner, Dummy) { }

__fastcall TDbEngineErrorDlg(HWND ParentWindow) : Forms::TForm(ParentWindow) { }

Description

Call TDbEngineErrorDlg indirectly, using the new keyword, to display BDE error messages in a TDbEngineErrorDlg dialog. Create a global instance in the project file or main form’s constructor and call HookExceptions to replace the default error handling with TDbEngineErrorDlg for all EDBEngineError exceptions. Alternately, create a temporary TDbEngineErrorDlg in a catch statement for an EDBEngineError exception and call ShowException to display the dialog for specific errors.

Pass a single Component as a parameter to provide the dialog with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax.

TDbEngineErrorDlg allows two additional forms of constructor syntax, but they are rarely used: Pass a component and an integer to create a TDbEngineErrorDlg instance without streaming in its properties and embedded controls. Pass a window handle as a parameter to embed the dialog in a non-VCL window.


TDbEngineErrorDlg::~TDbEngineErrorDlg

TDbEngineErrorDlg

Frees the memory associated with the TDbEngineErrorDlg object.

__fastcall virtual ~TDbEngineErrorDlg(void) { }

Description

Do not call ~TDbEngineErrorDlg directly. Instead, use the delete keyword on the object, which causes ~TDbEngineErrorDlg to be invoked automatically.

It is not necessary to call the destructor for TDbEngineErrorDlg dialogs that are created with an Owner.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm

TForm


TDBError

Hierarchy	Properties	Methods	See also

TDBError represents Borland Database Engine errors for the EDBEngineError exception class.

Unit

dbtables

Description

An EDBEngineError exception is raised when Borland Database Engine errors occur. EDBEngineError reads the stack of BDE errors and creates a separate TDBError object to represent each one. These TDBError objects are contained in the Errors property of EDBEngineError.

The categories and subcodes for BDE errors are defined in BDE.HPP.


TDBError properties

TDBError	Alphabetically	Legend

In TDBError

Category

ErrorCode

Message

NativeError

SubCode


TDBError properties

TDBError	By object	Legend

Category

ErrorCode

Message

NativeError

SubCode


TDBError::Category

TDBError 	See also

Indicates the category of error referenced by ErrorCode.

__property Byte Category = {read=GetCategory, nodefault};

Description

Category contains the high byte of the BDE error code.


TDBError::ErrorCode

TDBError	See also

Indicates the error code returned by the BDE.

__property Word ErrorCode = {read=FErrorCode, nodefault};

Description

Use ErrorCode to determine the error code returned by the BDE. It consists of a Category and a SubCode. Use the DBIError procedure to raise an exception for a value of ErrorCode.


TDBError::Message

TDBError

Specifies the text of the error message.

__property System::AnsiString Message = {read=FMessage};

Description

Message contains the remote server message for native (server) errors, or the BDE message associated with ErrorCode for non-server errors.


TDBError::NativeError

TDBError 	See also

Indicates the remote error code returned from the server.

__property int NativeError = {read=FNativeError, nodefault};

Description

Use NativeError to determine whether the error represents a remote error received from the database server. If NativeError is 0, the error is not a server error.


TDBError::SubCode

TDBError 	See also

Indicates the subcode of the error referenced by ErrorCode.

__property Byte SubCode = {read=GetSubCode, nodefault};

Description

SubCode contains the low byte of the BDE error code.


TDBError methods

TDBError	Alphabetically

In TDBError

~TDBError

TDBError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDBError methods

TDBError	By object

~TDBError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDBError


TDBError::TDBError

TDBError	See also

Initializes an instance of TDBError using error information returned by the BDE.

__fastcall TDBError(EDBEngineError* Owner, Word ErrorCode, int NativeError, char * Message);

Description

TDBError’s TDBError method is called by the TDBError method of EDBEngineError, just as TDBError’s Free method is called by the ~TDBError method of EDBEngineError.


TDBError::~TDBError

TDBError	See also

~TDBError frees the memory associated with the TDBError object.

__fastcall virtual ~TDBError(void) { }

Description

Do not call ~TDBError directly. Instead, use the delete keyword on the object, which causes ~TDBError to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject


TDBGridColumns

Hierarchy	Properties	Methods	See also

TDBGridColumns represents a container for TColumn objects.

Unit

dbgrids

Description

Each TDBGridColumns holds a collection of TColumn objects in a data grid (TDBGrid). TDBGridColumns maintains an index of the columns in its Items array. The Count property contains the number of columns in the collection. At design time, use the data grid’s Columns editor to add, remove, or modify columns.


TDBGridColumns properties

TDBGridColumns	Alphabetically	Legend

In TDBGridColumns

Grid

Items

State

Derived from TCollection

Count

ItemClass


TDBGridColumns properties

TDBGridColumns	By object	Legend

Count

Grid

ItemClass

Items

State


TDBGridColumns::Grid

TDBGridColumns	See also

Indicates the data-grid control to which the TDBGridColumns instance belongs.

__property TCustomDBGrid* Grid = {read=FGrid};

Description

The read-only Grid property indicates which data-grid control (TDBGrid) owns the TDBGridColumns object.


TDBGridColumns::Items

TDBGridColumns 	See also

Lists the columns in the collection.

__property TColumn* Items[int Index] = {read=GetColumn, write=SetColumn};

Description

Use Items to access individual columns. The value of the Index parameter corresponds to the Index property of TColumn. It represents the position of the column in the data grid.

Edit1->Text = DBGrid1->Columns->Items[0]->FieldName;


TDBGridColumns::State

TDBGridColumns	See also

Determines whether the columns in the data grid are dependent on dataset fields.

__property TDBGridColumnsState State = {read=GetState, write=SetState, nodefault};

Description

If State is set to csDefault, columns in the data grid are generated dynamically from information in the grid’s associated dataset. The appearance, order, and other properties of the columns are determined by the dataset fields. Changes made to the columns are reflected in the dataset fields, and vice versa.

If State is set to csCustomized, many properties of the data-grid columns are independent of the associated dataset. For example, a column’s title caption is, by default, the same as the associated field’s DisplayLabel property; if State is csCustomized, however, the column title’s Caption property and the field’s DisplayLabel property can be changed independently. In fact, a customized (or “persistent”) column need not be associated with a dataset field at all.

Note:	If the Columns editor is used to configure data-grid columns, State is automatically set to csCustomized. Changing the State property at runtime deletes all existing columns.


TDBGridColumns methods

TDBGridColumns	Alphabetically

In TDBGridColumns

~TDBGridColumns

Add

LoadFromFile

LoadFromStream

RebuildColumns

RestoreDefaults

SaveToFile

SaveToStream

TDBGridColumns

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDBGridColumns methods

TDBGridColumns	By object

~TDBGridColumns

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

RebuildColumns

RestoreDefaults

SafeCallException

SaveToFile

SaveToStream

TDBGridColumns


TDBGridColumns.Add

TDBGridColumns	See also

Creates a new TColumn instance and adds it to the Items array.

HIDESBASE TColumn* __fastcall Add(void);

Description

Add returns the new column. At design time, use the data grid’s Columns editor to add columns to the grid.


TDBGridColumns::TDBGridColumns

TDBGridColumns	See also

Creates and initializes a TDBGridColumns object.

__fastcall TDBGridColumns(TCustomDBGrid* Grid, System::TMetaClass* ColumnClass);

Description

The TDBGridColumns method takes two parameters: a data-grid instance object and TColumn (or the name of a class derived from TColumn).


TDBGridColumns::LoadFromFile

TDBGridColumns	See also

Reads the file specified in FileName and loads the data into the TDBGridColumns object.

void __fastcall LoadFromFile(const System::AnsiString Filename);

Description

Use the LoadFromFile method to retrieve grid columns data from a file and load into a TDBGridColumns object.


TDBGridColumns::LoadFromStream

TDBGridColumns	See also

Reads grid columns data from a stream and stores the contents in the TDBGridColumns object.

void __fastcall LoadFromStream(Classes::TStream* S);

Description

Use the LoadFromStream method to read Stream and store the contents in the TDBGridColumns object.


TDBGridColumns::RebuildColumns

TDBGridColumns

Deletes existing columns and generates new columns from the dataset associated with the grid.

void __fastcall RebuildColumns(void);

Description

RebuildColumns initializes the TDBGridColumns object by deleting all existing columns, then creating new ones from the grid’s associated dataset. If the grid is not connected to a dataset, RebuildColumns simply deletes any existing columns.


TDBGridColumns::RestoreDefaults

TDBGridColumns	See also

Restores all columns to their default settings.

void __fastcall RestoreDefaults(void);

Description

RestoreDefaults iterates through the Items array, calling the RestoreDefaults method for each TColumn object. This method removes all changes made to properties of the TColumn objects and restores the default settings.


TDBGridColumns::SaveToFile

TDBGridColumns	See also

Saves the TDBGridColumns object to the file specified in FileName.

void __fastcall SaveToFile(const System::AnsiString Filename);

Description

Use the SaveToFile method to store TDBGridColumns data to a text file.


TDBGridColumns::SaveToStream

TDBGridColumns	See also

Writes a stream with the name passed in Stream with the contents of the TDBGridColumns object.

void __fastcall SaveToStream(Classes::TStream* S);

Description

Use the SaveToStream method to stream out TDBGridColumns data.


TDBGridColumns::~TDBGridColumns

TDBGridColumns	See also

~TDBGridColumns frees the memory associated with the TDBGridColumns object.

__fastcall virtual ~TDBGridColumns(void) { }

Description

Do not call ~TDBGridColumns directly. Instead, use the delete keyword on the object, which causes ~TDBGridColumns to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


 TDBGrid

Hierarchy	Properties	Methods	Events	See also

TDBGrid displays and manipulates records from a dataset in a tabular grid.

Unit

dbgrids

Description

Put a TDBGrid object on a form to display and edit the records from a database table or query. Applications can use the data grid to insert, delete, or edit data in the database, or simply to display it.

At runtime, users can use the database navigator (TDBNavigator) to move through data in the grid, and to insert, delete, and edit the data. Edits that are made in the data grid are not posted to the underlying dataset until the user moves to a different record or closes the application.

TDBGrid implements the generic behavior introduced in TCustomDBGrid. TDBGrid publishes many of the properties inherited from TCustomDBGrid, but does not introduce any new behavior.


TDBGrid properties

TDBGrid	Alphabetically	Legend

Derived from TCustomDBGrid

Columns

DataSource

DefaultDrawing

FieldCount

Fields

Options

ReadOnly

SelectedField

SelectedIndex

SelectedRows

TitleFont

Derived from TCustomGrid

BorderStyle

EditorMode

FixedColor

Derived from TCustomControl

Canvas

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBGrid properties

TDBGrid	By object	Legend

Align

BorderStyle

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataSource

DefaultDrawing

DesignInfo

DragCursor

DragMode

EditorMode

Enabled

FieldCount

Fields

FixedColor

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

Left

Name

Options

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

SelectedField

SelectedIndex

SelectedRows

ShowHint

Showing

TabOrder

TabStop

Tag

TitleFont

Top

VCLComObject

Visible

Width

WindowProc


TDBGrid events

TDBGrid	Alphabetically	Legend

Derived from TCustomDBGrid

OnCellClick

OnColEnter

OnColExit

OnColumnMoved

OnDrawColumnCell

OnDrawDataCell

OnEditButtonClick

OnTitleClick

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDBGrid events

TDBGrid	By object	Legend

OnCellClick

OnColEnter

OnColExit

OnColumnMoved

OnDblClick

OnDragDrop

OnDragOver

OnDrawColumnCell

OnDrawDataCell

OnEditButtonClick

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnStartDrag

OnTitleClick


TDBGrid methods

TDBGrid	Alphabetically

In TDBGrid

~TDBGrid

TDBGrid

Derived from TCustomDBGrid

DefaultDrawColumnCell

DefaultDrawDataCell

ValidFieldIndex

Derived from TCustomGrid

MouseCoord

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBGrid methods

TDBGrid	By object

~TDBGrid

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultDrawColumnCell

DefaultDrawDataCell

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

MouseCoord

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBGrid

Update

UpdateControlState

ValidFieldIndex


TDBGrid::TDBGrid

TDBGrid

Creates a new TDBGrid object.

__fastcall virtual TDBGrid(Classes::TComponent* AOwner) : Dbgrids::TCustomDBGrid(AOwner) { }

__fastcall TDBGrid(HWND ParentWindow) : Dbgrids::TCustomDBGrid(ParentWindow) { }

Description

Do not call TDBGrid directly when creating a TDBGrid object at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TDBGrid object. TDBGrid objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TDBGrid object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TDBGrid object in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TDBGrid::~TDBGrid

TDBGrid

~TDBGrid frees the memory associated with the TDBGrid object.

__fastcall virtual ~TDBGrid(void) { }

Description

Do not call ~TDBGrid directly. Instead, use the delete keyword on the object, which causes ~TDBGrid to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGrid

TCustomDBGrid


 TDBImage

Hierarchy	Properties	Methods	Events	See also

TDBImage represents a graphic image from a BLOB (binary large object) field of the current record of a dataset.

Unit

dbctrls

Description

Use TDBImage to represent the value of graphic fields. TDBImage allows a form to display graphical data from a dataset. TDBImage can allow the user to edit graphical data using the clipboard. While the application is running and the database image control has focus, users can cut, copy, and paste using the standard windows accelerator keys (Ctrl+X, Ctrl+C, and Ctrl+V). Users can return to the original state of the database image control by pressing Esc before moving to another record.

If the application doesn’t require the data-aware capabilities of TDBImage, use an image control (TImage) instead to conserve system resources.


TDBImage properties

TDBImage	Alphabetically	Legend

In TDBImage

AutoDisplay

BorderStyle

Center

DataField

DataSource

Field

Picture

QuickDraw

ReadOnly

Stretch

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBImage properties

TDBImage	By object	Legend

Align

AutoDisplay

BorderStyle

BoundsRect

Brush

Center

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

Picture

PopupMenu

QuickDraw

ReadOnly

ShowHint

Showing

Stretch

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TDBImage::AutoDisplay

TDBImage	See also

Determines whether to automatically display the contents of a graphic BLOB in the database image control.

__property bool AutoDisplay = {read=FAutoDisplay, write=SetAutoDisplay, default=1};

Description

If AutoDisplay is true (the default value), the image automatically displays new data when the underlying BLOB field changes (such as when moving to a new record).

If AutoDisplay is false, the image clears whenever the underlying BLOB field changes. To display the data, the user can double-click on the control or select it and press Enter. In addition, calling the LoadPicture method ensures that the control is showing data.

Change the value of AutoDisplay to false if the automatic loading of BLOB fields seems to take too long.


TDBImage::BorderStyle

TDBImage	See also

Determines whether the database image control has a border.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Set BorderStyle to specify whether a single line border should be drawn around the database image control. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border


TDBImage::Center

TDBImage	See also	Example

Determines whether to center the image in the image control.

__property bool Center = {read=FCenter, write=SetCenter, default=1};

Description

When the image does not fit perfectly within the image control, use Center to position the image. When Center is true, the image is centered in the control. When Center is false, the upper left corner of the image is positioned at the upper left corner of the control.

Note:	Center has no effect if the Stretch property is true.


TDBImage::DataField

TDBImage	See also

Specifies the field from which the database image displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Use DataField to bind the image control to a field in the dataset. To fully specify a database field, both the dataset and the field within that dataset must be defined. The DataSource property of the image control specifies the dataset which contains the DataField. DataField should specify a graphic field.


TDBImage::DataSource

TDBImage	See also

Links the image control to a dataset.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use DataSource to link the image control to a dataset in which the data can be found. To fully specify a database field for the image control, both the dataset and a field within that dataset must be defined. Use the DataField property to specify the particular field within the dataset.


TDBImage::Field

TDBImage	See also

Specifies the TField component the database image is linked to.

__property Db::TField* Field = {read=GetField};

Description

Read Field to get direct access to the contents and properties of the database field without going through the image control’s window. Use Field to change the contents of the database field programmatically. Use the Picture property to set the value of the field and display it in the image control’s window.


TDBImage::Picture

TDBImage	See also

Represents the image that appears on the database image control.

__property Graphics::TPicture* Picture = {read=FPicture, write=SetPicture};

Description

Read Picture to obtain the TPicture object that represents the value of the field. Set Picture to programmatically change the value of the graphic field. The property value is a TPicture object which can contain an icon, metafile, bitmap, or other graphic object.


TDBImage::QuickDraw

TDBImage	See also

Specifies whether the image is displayed using a palette.

__property bool QuickDraw = {read=FQuickDraw, write=FQuickDraw, default=1};

Description

Set QuickDraw to specify whether a customized palette should be used when displaying field values. If false, a palette is used, to provide the best possible image quality at the expense of additional processing time. If true, no special palette is used, which is faster, but results in poorer picture quality, especially with 256-color images on a 256-color video driver.


TDBImage::ReadOnly

TDBImage	See also

Determines whether the user can change the contents of the field using the image control.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Set ReadOnly to true to prevent the user from changing the contents of the database field. When ReadOnly is true, the image control is used only to display the contents of the field. If ReadOnly is false, the user can change the field's value as long as the dataset is in edit mode.


TDBImage::Stretch

TDBImage	See also	Example

Determines whether bitmaps and metafiles assume the size and shape of the database image.

__property bool Stretch = {read=FStretch, write=SetStretch, default=0};

Description

Set Stretch to true to cause the picture to assume the size and shape of the image control. When the image control resizes, the picture resizes also. Stretch resizes the height and width of the image independently. Thus, unlike a simple change in magnification, stretch can distort the image if the image control is not the same shape as the image.


TDBImage events

TDBImage	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBImage events

TDBImage	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBImage methods

TDBImage	Alphabetically

In TDBImage

~TDBImage

CopyToClipboard

CutToClipboard

LoadPicture

PasteFromClipboard

TDBImage

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBImage methods

TDBImage	By object

~TDBImage

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

LoadPicture

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBImage

Update

UpdateControlState


TDBImage::CopyToClipboard

TDBImage	See also

Copies the picture in the image control to the Clipboard.

void __fastcall CopyToClipboard(void);

Description

Use CopyToClipboard to put a copy of the graphic specified by the Picture property in the Clipboard.


TDBImage::TDBImage

TDBImage	See also

Creates and initializes an instance of TDBImage.

__fastcall virtual TDBImage(Classes::TComponent* AOwner);

__fastcall TDBImage(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Call TDBImage indirectly, using the new keyword, to create a TDBImage object.

Pass a single Component as a parameter to provide the TDBLookupComboBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TDBImage in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor to allocate and initialize a generic control object, TDBImage

•	Adds csOpaque, csReplicatable to the ControlStyle,

•	Sets TabStop, AutoDisplay and Center to true and sets BorderStyle to bsSingle,

•	Creates a TPicture object and assigns it to the Picture property,

•	Initializes the height and width of the control,

•	Creates and initializes the helper objects needed to link to a dataset.


TDBImage::CutToClipboard

TDBImage	See also

Deletes the image in the control and copies it to the Clipboard.

void __fastcall CutToClipboard(void);

Description

Use the CutToClipboard method to delete the image in the control when copying it to the Clipboard. CutToClipboard gives the associated field a null value.


TDBImage::~TDBImage

TDBImage	See also

Destroys an instance of TDBImage.

__fastcall virtual ~TDBImage(void);

Description

Do not call ~TDBImage directly in an application. Instead, call delete.

~TDBImage frees the helper objects of the TDBImage before calling the parent object's destructor.


TDBImage::LoadPicture

TDBImage	See also

Loads the image stored in the field into the database image control.

void __fastcall LoadPicture(void);

Description

If the value of the AutoDisplay property is false, the image of a database image control is not automatically loaded. If AutoDisplay is false, control when the image is loaded at runtime by calling LoadPicture when the image should appear in the control.


TDBImage::PasteFromClipboard

TDBImage	See also

Copies the contents of the Clipboard to the control.

void __fastcall PasteFromClipboard(void);

Description

Use PasteFromClipboard to set the field value to an image stored in the Clipboard.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


 TDBListBox

Hierarchy	Properties	Methods	Events	See also

TDBListBox represents a data-aware list box that allows the user to change the value of the field of the current record in a dataset by selecting an item from a list.

Unit

dbctrls

Description

Use TDBListBox to add a list box to a form that permits users to change a field value from a fixed set of choices.

If the application doesn’t require the data-aware capabilities of TDBListBox, use a list box (TListBox) instead to conserve system resources.

Component writers wanting to create a customized list box objects should use TCustomListBox as a base class.


TDBListBox properties

TDBListBox	Alphabetically	Legend

In TDBListBox

DataField

DataSource

Field

Items

ReadOnly

Derived from TCustomListBox

BorderStyle

Canvas

IntegralHeight

ItemHeight

ItemIndex

SelCount

Selected

Style

TopIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBListBox properties

TDBListBox	By object	Legend

Align

BorderStyle

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IntegralHeight

ItemHeight

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

SelCount

Selected

ShowHint

Showing

Style

TabOrder

TabStop

Tag

Top

TopIndex

VCLComObject

Visible

Width

WindowProc


TDBListBox::DataField

TDBListBox	See also

Identifies the field whose value is displayed by the listbox.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Set DataField to specify which field is represented by the listbox. The listbox displays the current value of this field, and allows the user to set the value of this field on the current record. The dataset the field is located in is specified by the DataSource property.


TDBListBox::DataSource

TDBListBox	See also

Links the listbox to a dataset.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Specify the data source component that identifies the dataset the data is found in. To allow the listbox to represent the data for a field, both the DataSource and the DataField properties must be set.


TDBListBox::Field

TDBListBox	See also

Identifies the TField object the listbox is linked to.

__property Db::TField* Field = {read=GetField};

Description

Use the Field object when you want to change the value of the data in the field programmatically.


TDBListBox::Items

TDBListBox	See also

Contains the strings that appear in the list box.

__property Items  = {write=SetItems};

Description

Use Items to specify the values the user can choose from. Because Items is an object of type TStrings, you can add, delete, insert, and move items using the Add, Delete, Insert, Exchange, and Move methods of the TStrings object. For example, to add each string to the listbox, write a line of code such as the following:

DBListBox1->Items->Add("AFieldValue");

The ItemIndex property determines which item is selected, if any.


TDBListBox::ReadOnly

TDBListBox	See also

Determines if the user can change the field value using the listbox.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Set ReadOnly to specify whether the listbox should be used for display purposes only. If ReadOnly is true, the listbox can only be used to display the value of the field on the current record. If ReadOnly is false, the user can use the listbox to change the field’s value to one of the values in the Items list.


TDBListBox events

TDBListBox	Alphabetically	Legend

Derived from TCustomListBox

OnDrawItem

OnMeasureItem

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBListBox events

TDBListBox	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDrawItem

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMeasureItem

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBListBox methods

TDBListBox	Alphabetically

In TDBListBox

~TDBListBox

TDBListBox

Derived from TCustomListBox

Clear

ItemAtPos

ItemRect

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBListBox methods

TDBListBox	By object

~TDBListBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

ItemAtPos

ItemRect

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBListBox

Update

UpdateControlState


TDBListBox::TDBListBox

TDBListBox	See also

Creates and initializes an instance of TDBListBox.

__fastcall virtual TDBListBox(Classes::TComponent* AOwner);

__fastcall TDBListBox(HWND ParentWindow) : Stdctrls::TCustomListBox(ParentWindow) { }

Description

Call TDBListBox indirectly, using the new keyword, to create a DB list box at runtime. For TDBListBox objects placed on forms or data modules at design time, TDBListBox is called automatically.

Pass a single Component as a parameter to provide the TDBListBoxctor syntax. Pass a window handle as a parameter to embed the DB list box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor to allocate and initialize a generic list box object, TDBListBox creates and initializes the helper objects needed to link to a dataset.


TDBListBox::~TDBListBox

TDBListBox	See also

Destroys an instance of TDBListBox.

__fastcall virtual ~TDBListBox(void);

Description

Do not call ~TDBListBox directly in an application. Instead, call delete.

~TDBListBox frees the helper objects of the TDBListBox before calling the parent object's destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomListBox


 TDBLookupComboBox

Hierarchy	Properties	Methods	Events	See also

TDBLookupComboBox represents a combo box that identifies a set of field values in one dataset with a corresponding set of values from another dataset.

Unit

dbctrls

Description

Use TDBLookupComboBox to provide the user with a convenient drop-down list of lookup items for filling in fields that require data from another dataset.

If TDBLookupComboBox is linked to a lookup field component, it automatically reads the relationship between the field value and the lookup values in the lookup dataset from the field component. The relationship between field values and the corresponding values in the lookup dataset can also be explicitly set using the properties of the lookup combo box when the combo box is not linked to a lookup field component.


TDBLookupComboBox properties

TDBLookupComboBox	Alphabetically	Legend

In TDBLookupComboBox

DropDownAlign

DropDownRows

DropDownWidth

ListVisible

Text

Derived from TDBLookupControl

DataField

DataSource

Field

KeyField

KeyValue

ListField

ListFieldIndex

ListSource

ReadOnly

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBLookupComboBox properties

TDBLookupComboBox	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

DropDownAlign

DropDownRows

DropDownWidth

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

KeyField

KeyValue

Left

ListField

ListFieldIndex

ListSource

ListVisible

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TDBLookupComboBox::DropDownAlign

TDBLookupComboBox	See also

Specifies how the drop-down list is aligned relative to its edit box.

__property TDropDownAlign DropDownAlign = {read=FDropDownAlign, write=FDropDownAlign, default=0};

Description

Use DropDownAlign to specify the position of the drop-down list relative to the edit region of the lookup combo box. The drop down list can be aligned to the left or right, or centered with the edit box.


TDBLookupComboBox::DropDownRows

TDBLookupComboBox	See also

Specifies the number of items displayed in the drop-down list of the TDBLookupComboBox.

__property int DropDownRows = {read=FDropDownRows, write=FDropDownRows, default=7};

Description

Use DropDownRows to specify how many rows appear in the drop down list of the combo box. If there are more lookup items than DropDownRows, the lookup list box displays a scroll bar.


TDBLookupComboBox::DropDownWidth

TDBLookupComboBox	See also

Specifies the width, in pixels, of the drop-down list.

__property int DropDownWidth = {read=FDropDownWidth, write=FDropDownWidth, default=0};

Description

Use DropDownWidth to customize the width of the drop-down list. If DropDownWidth is 0 (the default), the drop-down list is the same width as the combo box.

DropDownWidth is useful when displaying multiple lookup fields, and therefore, multiple columns in the database lookup combo box.


TDBLookupComboBox::ListVisible

TDBLookupComboBox	See also

Specifies whether the lookup list is open or “dropped-down”.

__property bool ListVisible = {read=FListVisible, nodefault};

Description

Read ListVisible to determine whether the list of lookup values is currently in the open (dropped-down) position. If ListVisible is true, the list is open; if ListVisible is false, the list is closed.


TDBLookupComboBox::Text

TDBLookupComboBox	See also

Indicates the lookup value that corresponds to the value of the field on the current record.

__property System::AnsiString Text = {read=FText};

Description

Read Text to determine the currently selected lookup value. Text is the value that appears in the edit region of the lookup combo box. The user can change the value of Text by entering a new value if ReadOnly is false and the dataset is in edit mode.


TDBLookupComboBox events

TDBLookupComboBox	Alphabetically	Legend

In TDBLookupComboBox

OnCloseUp

OnDropDown

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBLookupComboBox events

TDBLookupComboBox	By object	Legend

OnClick

OnCloseUp

OnDragDrop

OnDragOver

OnDropDown

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBLookupComboBox::OnCloseUp

TDBLookupComboBox	See also

Occurs immediately after an opened or “dropped-down” list is closed.

__property Classes::TNotifyEvent OnCloseUp = {read=FOnCloseUp, write=FOnCloseUp};

Description

Write an OnCloseUp event handler to respond when the combo box list is closed. When the list is closed, the value that corresponds to the selected lookup value is assigned to the field. The list can be closed by the user or by calling the CloseUp method


TDBLookupComboBox::OnDropDown

TDBLookupComboBox	See also

Occurs immediately before the lookup list is opened.

__property Classes::TNotifyEvent OnDropDown = {read=FOnDropDown, write=FOnDropDown};

Description

Write an OnDropDown event handler to take specific action before the lookup list is displayed to the user. The list can be opened by the user or by calling the DropDown method.


TDBLookupComboBox methods

TDBLookupComboBox	Alphabetically

In TDBLookupComboBox

~TDBLookupComboBox

CloseUp

DropDown

TDBLookupComboBox

Derived from TDBLookupControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBLookupComboBox methods

TDBLookupComboBox	By object

~TDBLookupComboBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

CloseUp

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

DropDown

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBLookupComboBox

Update

UpdateControlState


TDBLookupComboBox::CloseUp

TDBLookupComboBox	See also

Closes an opened or “dropped-down” list.

void __fastcall CloseUp(bool Accept);

Description

Call CloseUp to programmatically close the list of the lookup combo box. The Accept parameter determines whether to modify the field value with the value that corresponds to the selected value in the lookup list.


TDBLookupComboBox::TDBLookupComboBox

TDBLookupComboBox	See also

Creates and initializes an instance of TDBLookupComboBox.

__fastcall virtual TDBLookupComboBox(Classes::TComponent* AOwner);

__fastcall TDBLookupComboBox(HWND ParentWindow) : Dbctrls::TDBLookupControl(ParentWindow) { }

Description

Call TDBLookupComboBox indirectly, using the new keyword, to create a DB lookup combo box at runtime. For TDBLookupComboBox objects placed on forms or data modules at design time, TDBLookupComboBox is called automatically.

Pass a single Component as a parameter to provide the TDBLookupComboBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the DB lookup combo box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor to allocate and initialize a generic list box object, TDBLookupComboBox creates and initializes various helper objects .


TDBLookupComboBox::DropDown

TDBLookupComboBox	See also

Opens or “drops down” the lookup list so that the user can choose a lookup value.

void __fastcall DropDown(void);

Description

Call DropDown to programmatically open the lookup list. Before the list is displayed, an OnDropDown event is generated.


TDBLookupComboBox::~TDBLookupComboBox

TDBLookupComboBox

Frees the memory associated with the TDBLookupComboBox object.

__fastcall virtual ~TDBLookupComboBox(void) { }

Description

Do not call ~TDBLookupComboBox directly. Instead, use the delete keyword on the object, which causes ~TDBLookupComboBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TDBLookupControl


TDBLookupControl

Hierarchy	Properties	Methods	See also

TDBLookupControl is an abstract base class for controls that provide the user with a convenient list of lookup items for filling in fields that require data from another dataset.

Unit

dbctrls

Description

Use TDBLookupControl as a base class when defining controls that permit the user to set a field value by selecting a corresponding value from another dataset. The TDBLookupComboBox and TDBLookupListBox controls are both descended from the TDBLookupControl and provide the user with automatic lookup capabilities that are implemented in the TDBLookupControl object.

Do not create instances of TDBLookupControl. Instead, instantiate a descendant of TDBLookupControl to allow the user to set field values from a set of lookup values.


TDBLookupControl properties

TDBLookupControl	Alphabetically	Legend

In TDBLookupControl

DataField

DataSource

Field

KeyField

KeyValue

ListField

ListFieldIndex

ListSource

ReadOnly

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBLookupControl properties

TDBLookupControl	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DataField

DataSource

DesignInfo

Enabled

Field

Handle

Height

HelpContext

Hint

KeyField

KeyValue

Left

ListField

ListFieldIndex

ListSource

Name

Owner

Parent

ParentColor

ParentWindow

ReadOnly

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TDBLookupControl::DataField

TDBLookupControl	See also

Identifies the field whose value is represented by the lookup control.

__property System::AnsiString DataField = {read=FDataFieldName, write=SetDataFieldName};

Description

Use DataField to bind the lookup control to a field in the dataset specified by the DataSource property. The DataField is the field whose value can be set by the lookup control, not the field which supplies the lookup values that are displayed by the lookup control.

If DataField specifies a lookup field component, there is no need to set the KeyField or ListField properties, as the field component contains all the information about the relationship between the data field value and the lookup value.


TDBLookupControl::DataSource

TDBLookupControl	See also

Links the lookup control to the dataset that contains the DataField.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use DataSource to specify the data source component that identifies the dataset the lookup control represents. The lookup control represents a field in one table by displaying the value of a corresponding field in another table. DataSource links to the dataset for the field the control represents, as opposed to the ListSource, which links the lookup control to the lookup table that holds the field that is actually displayed. If the lookup control is used to edit data, the field that actually gets changed is the one in the DataSource.


TDBLookupControl::Field

TDBLookupControl	See also

Identifies the TField object the lookup control represents.

__property Db::TField* Field = {read=FDataField};

Description

Use the Field object to directly access the field component for the field the lookup control represents. If Field is a lookup field, the properties of the field component describe the relationship between the field and the lookup dataset. To allow a lookup control to represent a set of lookup values that do not come from another dataset, use the DataField property to bind to a lookup field and use the LookupList property of the TField object to specify a list of lookup values.


TDBLookupControl::KeyField

TDBLookupControl	See also

Identifies the field in the ListSource dataset that must match the value of the DataField field.

__property System::AnsiString KeyField = {read=GetKeyFieldName, write=SetKeyFieldName};

Description

Use KeyField to link the ListSource of the lookup control to the DataSource. Although the name of the field specified as the KeyField does not have to be the same as the name of the field specified as the DataField, the two fields must have the same values.

After specifying the ListField, choose which field the lookup control will actually display with the ListField property.

If the DataField field is a lookup field, don't specify anything for KeyField or ListField; lookup controls automatically use the data field's LookupKeyFields property for KeyField.


TDBLookupControl::KeyValue

TDBLookupControl	See also

Represents the common value of the KeyField field and the DataField field.

__property System::Variant KeyValue = {read=FKeyValue, write=SetKeyValue};

Description

Use KeyField to determine the value represented by the lookup control (not the value displayed by the lookup control). When KeyValue is set, the lookup control attempts to find a record from the ListSource's dataset where the value of KeyField matches KeyValue. If such a match is found, the lookup control displays the value of ListField on that record.


TDBLookupControl::ListField

TDBLookupControl	See also

Identifies the field or fields whose values are displayed in the lookup control.

__property System::AnsiString ListField = {read=FListFieldName, write=SetListFieldName};

Description

The lookup control represents a field in one table by displaying the value of one or more corresponding fields in another table. ListField is the name of the field or fields in the lookup table that are actually displayed, as opposed to the DataField, which is the field in the DataSource that the lookup control actually represents, or the KeyField, which is the field in the lookup table with the same value as the DataField.

To fully specify the list fields, both a dataset for the lookup table and the fields within that dataset must be defined. The ListSource property of the lookup control specifies the dataset for the lookup table.

ListField can represent more than one field. Multiple field names should be separated by semicolons.

Before specifying ListField, specify the link between the two datasets using the KeyField property. If ListField is not set, lookup controls display KeyField field values by default. If the DataField field is a lookup field, don't specify anything for ListField; the data controls automatically use the lookup field's LookupResultField property as ListField.


TDBLookupControl::ListFieldIndex

TDBLookupControl	See also

Specifies which field from the ListField property is used for incremental searching.

__property int ListFieldIndex = {read=FListFieldIndex, write=FListFieldIndex, default=0};

Description

When the ListField property specifies more than one field, use ListFieldIndex to specify which of those fields is the one to use for incremental searches. For the TDBLookupComboBox object, ListFieldIndex also determines which field appears in the edit region of the combo box.

ListFieldIndex allows the most important value to appear in a position other than the first when all the values of the ListField fields are displayed. The value of ListFieldIndex must be less than the number of fields specified by the ListField property.


TDBLookupControl::ListSource

TDBLookupControl	See also

Identifies a data source for the data displayed in the lookup control.

__property Db::TDataSource* ListSource = {read=GetListSource, write=SetListSource};

Description

Set LookupSource to the data source that contains the KeyField and ListField fields. If the DataField field is a lookup field, don't specify anything for ListSource; data controls automatically use the lookup field's LookupDataSet property to create a data source.


TDBLookupControl::ReadOnly

TDBLookupControl	See also

Determines if the user can use the lookup control to set the value of the DataField field.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Use ReadOnly to specify whether the lookup control is used for display purposes only. If ReadOnly is true, the lookup control can only be used to display the lookup values that correspond to the value of the DataField field on the current record. If ReadOnly is false, the user can use the lookup control to change the field’s value.


TDBLookupControl methods

TDBLookupControl	Alphabetically	Legend

In TDBLookupControl

~TDBLookupControl

Notification

TDBLookupControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBLookupControl methods

TDBLookupControl	By object	Legend

~TDBLookupControl

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Notification

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBLookupControl

Update

UpdateControlState


TDBLookupControl::TDBLookupControl

TDBLookupControl	See also

Creates an instance of TDBLookupControl.

__fastcall virtual TDBLookupControl(Classes::TComponent* AOwner);

__fastcall TDBLookupControl(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Do not instantiate a TDBLookupControl object. To add a lookup control to a form, create an instance of a TDBLookupControl descendant using the new keyword. For TDBLookupControl objects placed on forms or data modules at design time, TDBLookupControl is called automatically.

After calling the parent object's constructor to allocate and initialize a generic custom control, TDBLookupControl creates and initializes the helper objects needed to link to the datasets.


TDBLookupControl::~TDBLookupControl

TDBLookupControl	See also

Destroys an instance of TDBLookupControl.

__fastcall virtual ~TDBLookupControl(void);

Description

Do not call ~TDBLookupControl directly in an application. Instead, call delete.

~TDBLookupControl frees the helper objects of the TDBLookupControl before calling the parent object's destructor.


TDBLookupControl::Notification

TDBLookupControl	See also

Responds to notifications that components are being created or destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the parent class's method, Notification checks whether the notification indicates the removal of DataSource or ListSource. If so, Notification sets the property to NULL.

Derived classes can override Notification method to handle additional notifications, but the parent class's method should be always be called.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


 TDBLookupListBox

Hierarchy	Properties	Methods	Events	See also

TDBLookupListBox provides a list of lookup items for filling in fields that require data from another dataset.

Unit

dbctrls

Description

Use TDBLookupListBox to provide users with a convenient list of lookup items to set a field value using the values of a field in another dataset. Lookup list boxes usually display values that are a represent a more meaningful description of the actual field value.

If TDBLookupListBox is linked to a lookup field component, it automatically reads the relationship between the field value and the lookup values in the lookup dataset from the field component. The relationship between field values and the corresponding values in the lookup dataset can also be explicitly set using the properties of the lookup list box when the list box is not linked to a lookup field component.


TDBLookupListBox properties

TDBLookupListBox	Alphabetically	Legend

In TDBLookupListBox

BorderStyle

RowCount

SelectedItem

Derived from TDBLookupControl

DataField

DataSource

Field

KeyField

KeyValue

ListField

ListFieldIndex

ListSource

ReadOnly

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBLookupListBox properties

TDBLookupListBox	By object	Legend

Align

BorderStyle

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

KeyField

KeyValue

Left

ListField

ListFieldIndex

ListSource

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

RowCount

SelectedItem

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TDBLookupListBox::BorderStyle

TDBLookupListBox	See also

Determines whether the lookup list box has a border.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Set BorderStyle to specify whether a border should be drawn around the lookup list box. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border


TDBLookupListBox::RowCount

TDBLookupListBox	See also

Specifies how many rows are visible in the list box.

__property int RowCount = {read=FRowCount, write=SetRowCount, stored=false, nodefault};

Description

Set RowCount to the number of rows displayed in the lookup list box. The list box is resized to match the specified number of rows. Resizing the list box (such as by changing its Height property) automatically changes the value of RowCount to match the new height.


TDBLookupListBox::SelectedItem

TDBLookupListBox	See also

Contains the value displayed in the list box that is currently selected.

__property System::AnsiString SelectedItem = {read=FSelectedItem};

Description

Read SelectedItem to determine the value the user selected using the lookup list box. If no item is selected, SelectedItem is an empty string.


TDBLookupListBox events

TDBLookupListBox	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBLookupListBox events

TDBLookupListBox	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBLookupListBox methods

TDBLookupListBox	Alphabetically

In TDBLookupListBox

~TDBLookupListBox

TDBLookupListBox

Derived from TDBLookupControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBLookupListBox methods

TDBLookupListBox	By object

~TDBLookupListBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBLookupListBox

Update

UpdateControlState


TDBLookupListBox::TDBLookupListBox

TDBLookupListBox	See also

Creates an instance of TDBLookupListBox.

__fastcall virtual TDBLookupListBox(Classes::TComponent* AOwner);

__fastcall TDBLookupListBox(HWND ParentWindow) : Dbctrls::TDBLookupControl(ParentWindow) { }

Description

Call TDBLookupListBox indirectly, using the new keyword, to create a DB lookup list box at runtime. For TDBLookupListBox objects placed on forms or data modules at design time, TDBLookupListBox is called automatically.

Pass a single Component as a parameter to provide the TDBLookupListBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the DB lookup list box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor to allocate and initialize a generic lookup control, TDBLookupListBox creates and initializes the helper objects needed to link to a dataset.


TDBLookupListBox::~TDBLookupListBox

TDBLookupListBox

~TDBLookupListBox frees the memory associated with the TDBLookupListBox object. Do not call ~TDBLookupListBox directly. Instead, use the delete keyword on the object, which causes ~TDBLookupListBox to be invoked automatically.

__fastcall virtual ~TDBLookupListBox(void) { }


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TDBLookupControl


TLoginDialog

Hierarchy	Properties	Methods	Events	See also

TLoginDialog is a login dialog box that can be used to provide login security within an application.

Unit

dblogdlg

Description

Use TLoginDialog to provide login security within an application. Usually a TLoginDialog object is created with the LoginDialogEx function and is used to provide secure access to local database tables. However, TLoginDialog can also be used as a base object for other types of login dialog boxes.


TLoginDialog properties

TLoginDialog	Alphabetically	Legend

Derived from TCustomForm

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

BorderIcons

BorderStyle

Canvas

ClientHandle

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

FormStyle

HelpFile

Icon

KeyPreview

MDIChildCount

MDIChildren

Menu

ModalResult

ObjectMenuItem

OleFormObject

Parent

PixelsPerInch

Position

PrintScale

Scaled

TileMode

Visible

WindowMenu

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TLoginDialog properties

TLoginDialog	By object	Legend

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

Align

AutoScroll

BorderIcons

BorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHandle

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

FormStyle

Handle

Height

HelpContext

HelpFile

Hint

HorzScrollBar

Icon

KeyPreview

Left

MDIChildCount

MDIChildren

Menu

ModalResult

Name

ObjectMenuItem

OleFormObject

Owner

Parent

ParentFont

ParentWindow

PixelsPerInch

PopupMenu

Position

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

TileMode

Top

VCLComObject

VertScrollBar

Visible

Width

WindowMenu

WindowProc

WindowState


TLoginDialog events

TLoginDialog	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnClose

OnCloseQuery

OnCreate

OnDeactivate

OnDestroy

OnHelp

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TLoginDialog events

TLoginDialog	By object	Legend

OnActivate

OnClick

OnClose

OnCloseQuery

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHelp

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TLoginDialog methods

TLoginDialog	Alphabetically

In TLoginDialog

~TLoginDialog

TLoginDialog

Derived from TForm

ArrangeIcons

Cascade

Next

Previous

Tile

Derived from TCustomForm

Close

CloseQuery

DefocusControl

FocusControl

GetFormImage

Hide

Print

Release

SendCancelMode

SetFocus

SetFocusedControl

Show

ShowModal

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TLoginDialog methods

TLoginDialog	By object

~TLoginDialog

ArrangeIcons

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Cascade

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

DefaultHandler

DefocusControl

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Next

PaintTo

Perform

Previous

Print

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetFocus

SetFocusedControl

SetTextBuf

Show

ShowModal

Tile

TLoginDialog

Update

UpdateControlState


TLoginDialog::TLoginDialog

TLoginDialog

Creates a new TLoginDialog object.

__fastcall virtual TLoginDialog(Classes::TComponent* AOwner) : Forms::TForm(AOwner) { }

__fastcall TLoginDialog(Classes::TComponent* AOwner, int Dummy) : Forms::	TForm(AOwner, Dummy) { }

__fastcall TLoginDialog(HWND ParentWindow) : Forms::TForm(ParentWindow) { }

Description

Call TLoginDialog indirectly, using the new keyword, to create a login dialog at runtime. Login dialogs added to forms or data modules at design time are created automatically.

Pass a single Component as a parameter to provide the login dialog with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a component and an integer to bypass the VCL streaming system that loads the properties and embedded objects of the dialog. This syntax is rarely used. Pass a window handle as a parameter to embed the login dialog in a non-VCL window. This syntax is used when the dialog is implemented as an ActiveX control that is embedded in a non-VCL window.


TLoginDialog::~TLoginDialog

TLoginDialog

Frees the memory associated with the TLoginDialog object.

__fastcall virtual ~TLoginDialog(void) { }

Description

Do not call ~TLoginDialog directly. Instead, use the delete keyword on the object, which causes ~TLoginDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm

TForm


 TDBMemo

Hierarchy	Properties	Methods	Events	See also

TDBMemo represents a multiline edit control that can display and edit a field in a dataset.

Unit

dbctrls

Description

Use TDBMemo to let users edit a field that may contain lengthy textual data or to simply display the contents of such a field. TDBMemo uses the Text property to represent the contents of the field.

TDBMemo permits multiple lines of text. Thus, TDBMemo is appropriate for long alphanumeric fields or text binary large objects (BLOBs). For short alphanumeric fields, consider using a TDBEdit component instead.

If the application doesn’t require the data-aware capabilities of TDBMemo, use a memo control (TMemo) instead, to conserve system resources.


TDBMemo properties

TDBMemo	Alphabetically	Legend

In TDBMemo

AutoDisplay

DataField

DataSource

Field

ReadOnly

Derived from TCustomMemo

Alignment

CaretPos

Lines

ScrollBars

WantTabs

WordWrap

Derived from TCustomEdit

BorderStyle

CanUndo

MaxLength

Modified

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBMemo properties

TDBMemo	By object	Legend

Align

Alignment

AutoDisplay

BorderStyle

BoundsRect

Brush

CanUndo

CaretPos

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

Left

Lines

MaxLength

Modified

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

ScrollBars

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

WantTabs

Width

WindowProc

WordWrap


TDBMemo::AutoDisplay

TDBMemo	See also 	Example

Determines whether to automatically display the contents of a memo or graphic BLOB in a database memo.

__property bool AutoDisplay = {read=FAutoDisplay, write=SetAutoDisplay, default=1};

Description

If AutoDisplay is true, the control automatically displays new data when the underlying BLOB field changes (such as when moving to a new record).

If AutoDisplay is false, the control shows only the field name whenever the underlying BLOB field changes. To display the data, the user can double-click on the control or select it and press Enter.

The effect of AutoDisplay is not purely cosmetic. The data shown by the TDBMemo is the value of the Text property. When AutoDisplay is false, if the data changes, the value of the Text property changes to the name of the field. Thus, if AutoDisplay is false, applications should be cautious about using the value of the Text property to ascertain the value of the underlying field.

Calling the LoadMemo method causes Text to update to the current value of the BLOB field. This change will also be reflected in the appearance of the control on screen.

Change the value of AutoDisplay to false if the automatic loading of BLOB fields takes too long.

Note:	AutoDisplay only applies to BLOB fields. If the control is bound to another type of text field, AutoDisplay has no effect.


TDBMemo::DataField

TDBMemo	See also

Specifies the name of the field for which the database memo displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Use DataField to link the memo control to a field in the dataset. Just setting DataField by itself will not link the memo control to a database field. Additionally, the dataset which contains the field must be specified by setting the DataSource property.


TDBMemo::DataSource

TDBMemo	See also

Links the memo control to the dataset that contains the field for which the memo control displays data.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Link the memo control with a dataset by setting DataSource to a data source component that identifies the desired dataset. Specify which field in the dataset contains the memo data using the DataField property.


TDBMemo::Field

TDBMemo	See also

Identifies the TField component the database memo is linked to.

__property Db::TField* Field = {read=GetField};

Description

Read Field to get direct access to the contents and properties of the database field without going through the edit window. Use Field to change the contents of the database field programmatically.

Use the Text property instead to change the contents of the memo control without immediately writing the changes to the record in the dataset. Changing the Text property allows the user to cancel the changes.


TDBMemo::ReadOnly

TDBMemo	See also

Determines whether the user can change the contents of the database memo.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

If ReadOnly is true, the user can't change the contents. If ReadOnly is false, the user can modify the contents.

The ReadOnly property determines whether the user can use the database memo to change the value of the field of the current record, or if the control only displays the value. If ReadOnly is false, the user can change the field's value as long as the dataset is in edit mode.


TDBMemo events

TDBMemo	Alphabetically	Legend

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBMemo events

TDBMemo	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBMemo methods

TDBMemo	Alphabetically	Legend

In TDBMemo

~TDBMemo

Change

KeyDown

KeyPress

LoadMemo

Notification

TDBMemo

WndProc

Derived from TCustomEdit

Clear

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBMemo methods

TDBMemo	By object	Legend

~TDBMemo

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

KeyPress

LoadMemo

MethodAddress

MethodName

NewInstance

Notification

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TDBMemo

Undo

Update

UpdateControlState

WndProc


TDBMemo::Change

TDBMemo	See also

Informs the data source of changes to the value of the text, before invoking the OnChange event handler.

DYNAMIC void __fastcall Change(void);

Description

Applications do not call the Change method directly: it is triggered automatically by Windows events. Derived classes can override the Change method to make additional responses to changes in the Text property. Any class that overrides the Change method should call the inherited method as well.


TDBMemo::TDBMemo

TDBMemo	See also

Creates an instance of TDBMemo.

__fastcall virtual TDBMemo(Classes::TComponent* AOwner);

__fastcall TDBMemo(HWND ParentWindow) : Stdctrls::TCustomMemo(ParentWindow) { }

Description

Do not call TDBMemo directly when creating a database memo at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created database memo. TDBMemo objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the database memo with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the database memo in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TDBMemo initializes the data handling aspects of a TDBMemo.


TDBMemo::~TDBMemo

TDBMemo	See also

Destroys an instance of TDBMemo.

__fastcall virtual ~TDBMemo(void);

Description

Do not call ~TDBMemo directly in an application. Instead, use the delete keyword which takes an indirect reference to a TDBMemo object.

~TDBMemo frees up the memory associated with data handling that was allocated in the constructor, before calling the parent object's destructor.


TDBMemo::KeyDown

TDBMemo	See also

Overrides the inherited method to put the dataset in an editing state if the user types Del or Shift+Insert.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

KeyDown first calls the inherited method, which calls the OnKeyDown event handler. KeyDown next attempts to put the dataset into an editing state when the user types Del or Shift+Insert. If the memo control is not linked to a dataset, KeyDown discards the keystroke. Derived classes can override KeyDown to handle additional key combinations, but the inherited method should always be called.


TDBMemo::KeyPress

TDBMemo	See also

KeyPress overrides the inherited method to handle any keystrokes that alter the state of the edit control.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

KeyPress first calls the inherited method, which calls the OnKeyPress event handler. Next, KeyPress checks the value of the key, and throws it away if it is not a valid character for the field type, or if there is no link to a database field. Valid characters cause KeyPress to attempt to put the dataset into edit mode.

If the field for the memo control is a text BLOB, pressing the Pause key causes KeyPress to call the LoadMemo method. Pressing the Escape key causes KeyPress to throw away unposted edits.


TDBMemo::LoadMemo

TDBMemo	See also 	Example

LoadMemo loads the text BLOB from the field in the database into the memo control.

void __fastcall LoadMemo(void);

Description

LoadMemo allows an application to control when the memo control displays the actual contents of a text BLOB field. Use LoadMemo to update the text in the memo control to the value of the field in the current record. LoadMemo only works with text BLOB fields, when the AutoDisplay property is false, so that the value of the field is not loaded automatically.


TDBMemo::Notification

TDBMemo	See also

Overrides the inherited method to respond to opRemove notifications on the DataSource.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the inherited method, Notification checks whether the notification indicates the removal of the DataSource. If so, Notification sets the DataSource property to NULL.

Derived classes can override Notification method to handle additional notifications, but the inherited method should be always be called.


TDBMemo::WndProc

TDBMemo	See also

Provides specific message responses for the memo control.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc overrides the WndProc for TWinControl to handle window messages that are specific to painting a TDBMemo control, and sends all others to the inherited WndProc.

Derived classes that override WndProc to provide specialized responses to messages should call the inherited WndProc at the end to dispatch any other messages.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMemo


 TDBNavigator

Hierarchy	Properties	Methods	Events	See also

TDBNavigator (the database navigator) is used to move through the data in a dataset and perform operations on the data, such as inserting a blank record or posting a record.

Unit

dbctrls

Description

Use the database navigator on forms that contain data-aware controls, such as TDBGrid or TDBEdit. TDBNavigator provides the user with control over the dataset when editing or viewing the data.

When the user chooses one of the navigator buttons, the appropriate action occurs on the dataset the navigator is linked to. For example, if the user clicks the Insert button, a blank record is inserted in the dataset.

TDBNavigator can show any or all of the following buttons:

Button	Purpose

First	Sets the current record to the first record in the dataset, disables the First and Prior buttons, and enables the Next and last buttons if they are disabled.

Prior	Sets the current record to the previous record and enables the Last and Next buttons if they are disabled.

Next	Sets the current record to the next record and enables the First and Prior buttons if they are disabled.

Last	Sets the current record to the last record in the dataset, disables the Last and Next buttons, and enables the First and Prior buttons if they are disabled.

Insert	Inserts a new record before the current record, and sets the dataset into Insert and Edit states.

Delete	Deletes the current record and makes the next record the current record.

Edit	Puts the dataset into Edit state so that the current record can be modified.

Post	Writes changes in the current record to the database.

Cancel	Cancels edits to the current record, restores the record display to its condition prior to editing, and turns off Insert and Edit states if they are active.

Refresh	Refreshes the buffered data in the associated dataset. For TQuery components, this button is disabled unless the RequestLive property is true.


TDBNavigator properties

TDBNavigator	Alphabetically	Legend

In TDBNavigator

ConfirmDelete

DataSource

Flat

Hints

VisibleButtons

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBNavigator properties

TDBNavigator	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConfirmDelete

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Flat

Handle

Height

HelpContext

Hint

Hints

Left

Name

Owner

Parent

ParentCtl3D

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

VisibleButtons

Width

WindowProc


TDBNavigator::ConfirmDelete

TDBNavigator	See also

Determines whether a message box appears asking the user to confirm record deletions initiated using the database navigator.

__property bool ConfirmDelete = {read=FConfirmDelete, write=FConfirmDelete, default=1};

Description

Use the ConfirmDelete property to help prevent the user from accidentally deleting a record from the dataset.

If ConfirmDelete is true, a message box appears when the user presses the delete button and the record isn't deleted unless the user chooses the OK button. If ConfirmDelete is false, no message box appears and the record is simply deleted.


TDBNavigator::DataSource

TDBNavigator	See also

Links the navigator to the dataset which it controls.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use the DataSource property to link the database navigator with a dataset. Specify the data source component that identifies the dataset the data is found in.


TDBNavigator::Flat

TDBNavigator	See also

Determines whether the buttons of the navigator have a three-dimensional (3-D) look with borders or two-dimensional look without borders.

__property bool Flat = {read=FFlat, write=SetFlat, default=0};

Description

When Flat is true, the navigator buttons appear flat and do not have borders separating them. When Flat is false, the buttons are clearly defined.


TDBNavigator::Hints

TDBNavigator	See also

Provides a way to customize the Help Hints for the buttons on the database navigator.

__property Classes::TStrings* Hints = {read=FHints, write=SetHints};

Description

Use the Hints property to supply Help Hints of your choosing for the individual navigator buttons. Each button has a default Help Hint. Hints allow the values of any or all of these default Help Hints to be replaced by customized hints.

Hints is a string list. Each hint is a string. The first string in the string list becomes the Help Hint for the first button on the navigator (the First button). The seventh hint becomes the Help Hint for the seventh button (the Edit button).

When specifying Hints at runtime, enter an empty string ("") for any Help Hint that should keep the default value. Simply leave the line blank when using the string list property editor of the Object Inspector for the Hints property.

Note:	To have the Help Hints appear at runtime, set the ShowHint property to true.


TDBNavigator::VisibleButtons

TDBNavigator	See also

Determines which buttons appear on the database navigator.

enum TNavigateBtn { nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh };

typedef Set<TNavigateBtn, nbFirst, nbRefresh>  TButtonSet;

__property TButtonSet VisibleButtons = {read=FVisibleButtons, write=SetVisible, default=1023};

Description

Use VisibleButtons to select which buttons appear on the navigator. Leave any of the navigator buttons out of the VisibleButtons set to hide those buttons and thereby prevent the user from performing certain operations. For example, to only allow the user to view the records in the dataset, VisibleButtons should include only the nbFirst, nbPrior, nbNext, and nbLast

The following buttons are available for VisibleButtons:

Button	Value	Action

First	nbFirst	Go to the first record

Prior	nbPrior	Go to the previous record

Next	nbNext	Go to the next record

Last	nbLast	Go to the last record

Insert	nbInsert	Insert a blank record

Delete	nbDelete	Deletes the current record

Edit	nbEdit	Permits editing of the current record

Post	nbPost	Posts the current record

Cancel	nbCancel	Cancels the current edit

Refresh	nbRefresh	Refreshes the data in the dataset


TDBNavigator events

TDBNavigator	Alphabetically	Legend

In TDBNavigator

BeforeAction

OnClick

Derived from TCustomPanel

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDBNavigator events

TDBNavigator	By object	Legend

BeforeAction

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnResize

OnStartDrag


TDBNavigator::BeforeAction

TDBNavigator	See also

Occurs when a button on the database navigator is clicked, before the action is executed.

enum TNavigateBtn { nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh };

typedef void __fastcall (__closure *ENavClick)(System::TObject* Sender, TNavigateBtn Button);

__property ENavClick BeforeAction = {read=FBeforeAction, write=FBeforeAction};

Description

Write a BeforeAction event handler to take specific action before the default response when a user clicks a button in the database navigator.

The Button parameter indicates which button was clicked.  It can have one of the following values:

Button	Value	Action

First	nbFirst	Go to the first record

Prior	nbPrior	Go to the previous record

Next	nbNext	Go to the next record

Last	nbLast	Go to the last record

Insert	nbInsert	Insert a blank record

Delete	nbDelete	Deletes the current record

Edit	nbEdit	Permits editing of the current record

Post	nbPost	Posts the current record

Cancel	nbCancel	Cancels the current edit

Refresh	nbRefresh	Refreshes the data in the dataset


TDBNavigator::OnClick

TDBNavigator	See also 	Example

Occurs when a button on the database navigator is clicked, after the action is executed.

enum TNavigateBtn { nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh };

typedef void __fastcall (__closure *ENavClick)(System::TObject* Sender, TNavigateBtn Button);

__property ENavClick OnClick = {read=FOnNavClick, write=FOnNavClick};

Description

Use the OnClick event handler to write code that responds to the click event. Because the buttons on the navigator already have default actions that occur when they are clicked, it isn’t necessary to write an OnClick event handler.

The OnClick event occurs when

•	The user clicks one the buttons on the navigator with the mouse

•	The user presses Spacebar while the navigator has focus.

•	The BtnClick method is called.

The Button parameter indicates which button was clicked.  It can have one of the following values:

Button	Value	Action

First	nbFirst	Go to the first record

Prior	nbPrior	Go to the previous record

Next	nbNext	Go to the next record

Last	nbLast	Go to the last record

Insert	nbInsert	Insert a blank record

Delete	nbDelete	Deletes the current record

Edit	nbEdit	Permits editing of the current record

Post	nbPost	Posts the current record

Cancel	nbCancel	Cancels the current edit

Refresh	nbRefresh	Refreshes the data in the dataset

Note:	The OnClick event occurs after the default action for the clicked button.


TDBNavigator methods

TDBNavigator	Alphabetically

In TDBNavigator

~TDBNavigator

BtnClick

SetBounds

TDBNavigator

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBNavigator methods

TDBNavigator	By object

~TDBNavigator

Assign

BeginDrag

BringToFront

Broadcast

BtnClick

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBNavigator

Update

UpdateControlState


TDBNavigator::BtnClick

TDBNavigator	See also 	Example

Simulates a button click on the database navigator, invoking the action of the button.

enum TNavigateBtn { nbFirst, nbPrior, nbNext, nbLast, nbInsert, nbDelete, nbEdit, nbPost, nbCancel, nbRefresh };

void __fastcall BtnClick(TNavigateBtn Index);

Description

Use BtnClick when you want the application, not the user, to control the database navigator. Call BtnClick, specifying a TNavigateBtn type as the value of the Index parameter, to invoke the command associated with the selected button.

The Index parameter can have one of the following values:

Value	Command

nbFirst	Go to the first record

nbPrior	Go to the previous record

nbNext	Go to the next record

nbLast	Go to the last record

nbInsert	Insert a blank record

nbDelete	Deletes the current record

nbEdit	Permits editing of the current record

nbPost	Posts the current record

nbCancel	Cancels the current edit

nbRefresh	Refreshes the data in the dataset

Note:	Calling BtnClick triggers the navigator’s OnClick event after the default action of the button.


TDBNavigator::TDBNavigator

TDBNavigator	See also

Creates an instance of TDBNavigator.

__fastcall virtual TDBNavigator(Classes::TComponent* AOwner);

__fastcall TDBNavigator(HWND ParentWindow) : Extctrls::TCustomPanel(ParentWindow) { }

Description

Do not call TDBNavigator directly when creating a DB navigator at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TDBNavigator object. DB navigators placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TDBNavigator object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the DB navigator in a non-VCL window. This syntax is used when the navigator is implemented as an ActiveX control that is embedded in a non-VCL window.

TDBNavigator creates the helper objects used to manage the buttons and the link to the dataset, and initializes some properties to affect the appearance of the navigator.


TDBNavigator::~TDBNavigator

TDBNavigator	See also

Destroys an instance of TDBNavigator.

__fastcall virtual ~TDBNavigator(void);

Description

Do not call ~TDBNavigator directly in an application. Instead, use the delete keyword, which calls ~TDBNavigator indirectly.

~TDBNavigator frees the helper objects that were instantiated in the TDBNavigator method before calling the parent object's destructor.


TDBNavigator::SetBounds

TDBNavigator	See also

Sets the database navigator's boundary properties all at once.

virtual void __fastcall SetBounds(int ALeft, int ATop, int AWidth, int AHeight);

Description

Call SetBounds when to set more than one of the navigator’s boundary properties at a time. The Left, Top, Width, and Height properties are set to the values passed in the ALeft, ATop, AWidth, and AHeight parameters, respectively. SetBounds arranges the buttons on the navigator to fit within the boundaries.

Although you can always set the individual boundaries, using SetBounds makes several changes at once without rearranging the buttons for each change.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomPanel


 TDBRadioGroup

Hierarchy	Properties	Methods	Events	See also

TDBRadioGroup represents a group of radio buttons connected to a database.

Unit

dbctrls

Description

Use TDBRadioGroup to group a set of data-aware radio buttons. Radio buttons that are contained directly in the same control component are said to be “grouped”; when a radio button is checked, all other radio buttons in its group become unchecked. Database radio groups provide an easy way to ensure that the user enters one (or at most one) of the options presented for a field. They are also useful for displaying data from fields that have only a few possible values.

To add radio buttons to a TDBRadioGroup, edit the Items property in the Object Inspector. Each string in Items makes a radio button appear in the group box with the string as its caption.

When the user selects a radio button, the “value” of the selected button becomes the contents of the linked field for the current record in the dataset. Specify values for the buttons by editing the Values property in the Object Inspector; the first string in Values corresponds to the first string in Items, and so forth. If no Values strings are set, each button’s caption serves as its value.


TDBRadioGroup properties

TDBRadioGroup	Alphabetically	Legend

In TDBRadioGroup

DataField

DataSource

Field

Items

ReadOnly

Value

Values

Derived from TCustomRadioGroup

Columns

ItemIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBRadioGroup properties

TDBRadioGroup	By object	Legend

Align

BoundsRect

Brush

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

Hint

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

ShowHint

Showing

TabOrder

TabStop

Tag

Top

Value

Values

VCLComObject

Visible

Width

WindowProc


TDBRadioGroup::DataField

TDBRadioGroup	See also

Specifies the field from which the radio group displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Use DataField to specify the name of the database field that the radio group will represent.


TDBRadioGroup::DataSource

TDBRadioGroup	See also

Determines where the database radio group obtains the data to display.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

DataSource holds a TDataSource object that points to a dataset component, such as a table. The dataset component should be linked to the database you want to access.


TDBRadioGroup::Field

TDBRadioGroup	See also

Identifies the TField component that the radio group is linked to.

__property Db::TField* Field = {read=GetField};

Description

Field holds the TField object that the linked dataset component creates to access the database.


TDBRadioGroup::Items

TDBRadioGroup	See also 	Example

Lists the radio buttons in the radio group.

__property Items  = {write=SetItems};

Description

Items holds a TStrings object that lists the captions of the radio buttons in the group. (To add or remove radio buttons, edit the Items list from the Object Inspector::) These captions become the “values” of the radio buttons, unless you override them in the Values property; when a button is selected, its value becomes the content of the linked field for the current record in the database.


TDBRadioGroup::ReadOnly

TDBRadioGroup	See also

Determines whether the user can select a different radio button in the group, and hence modify the data in the field.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

If ReadOnly is true, the radio group displays data from the current record, but cannot be used to change the contents of the field. The default is false.


TDBRadioGroup::Value

TDBRadioGroup

Holds the content of the linked field for the current record in the database.

__property System::AnsiString Value = {read=FValue, write=SetValue};

Description

Value holds the content of the linked field for the current record. If the user selects a different radio button, the Value property changes.


TDBRadioGroup::Values

TDBRadioGroup	See also 	Example

Determines the values of the radio buttons.

__property Classes::TStrings* Values = {read=FValues, write=SetValues};

Description

When the user selects a radio button, the “value” of that button is written to the linked field in the database. By default, the value of a button is simply the caption that appears next to it on the screen, as determined by the Items property.

In some cases, you may want the values of the radio buttons to differ from their captions. For example, if you use radio buttons to represent a database field whose content can be “Y” or “N”, you may want the buttons’ captions to be “Yes” and “No”. In this case, you would enter “Yes” and “No” in the Items list, and enter “Y” and “N” in the Values list.

You can edit the Values list in the Object Inspector, just as you would the Items list. To keep the buttons’ captions as their values, leave the Values property empty.


TDBRadioGroup events

TDBRadioGroup	Alphabetically	Legend

In TDBRadioGroup

OnChange

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDBRadioGroup events

TDBRadioGroup	By object	Legend

OnChange

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnStartDrag


TDBRadioGroup::OnChange

TDBRadioGroup

Occurs when the user changes the data in the linked field.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

The OnChange event occurs when a change is made to the contents of the database field accessed by the radio group. Use an OnChange event handler to implement any special processing that should be executed when the radio group is updated.


TDBRadioGroup methods

TDBRadioGroup	Alphabetically	Legend

In TDBRadioGroup

~TDBRadioGroup

CanModify

TDBRadioGroup

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBRadioGroup methods

TDBRadioGroup	By object	Legend

~TDBRadioGroup

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CanModify

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDBRadioGroup

Update

UpdateControlState


TDBRadioGroup::CanModify

TDBRadioGroup	See also

Determines whether the user can select a different radio button in the group.

virtual bool __fastcall CanModify(void);

Description

CanModify returns true if the radio group is linked to an editable data source and ReadOnly is set to false.


TDBRadioGroup::TDBRadioGroup

TDBRadioGroup

Creates and initializes a TDBRadioGroup instance.

__fastcall virtual TDBRadioGroup(Classes::TComponent* AOwner);

Description

TDBRadioGroup calls the parent object's constructor method, then initializes internal objects and variables used to control data access.


TDBRadioGroup::~TDBRadioGroup

TDBRadioGroup

Destroys the TDBRadioGroup instance and the radio buttons it contains.

__fastcall virtual ~TDBRadioGroup(void);

Description

~TDBRadioGroup frees internally created objects that control data access, then calls the parent object's destructor method.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGroupBox

TCustomRadioGroup


 TDBRichEdit

Hierarchy	Properties	Methods	Events	See also

TDBRichEdit represents a multiline edit control that can display and edit a rich text memo field in a dataset.

Unit

dbctrls

Description

Use a TDBRichEdit object to enable users to edit a database field in a rich text edit control. TDBRichEdit provides the properties and methods to enter and work with rich text. TDBRichEdit does not provide any user interface components to make these formatting options available to the user. Applications must implement the user interface components to surface the rich text capabilities of a TDBRichEdit object.

TDBRichEdit uses the Text property to represent the contents of the field.  Like other data-aware controls, TDBRichEdit controls automatically put the data source into edit mode when the value of the Text property is changed.  However, if only the formatting of the text is changed, but not the text itself, the application must explicitly put the data source into edit mode so that the changes will be saved. This should be implemented as part of the user interface for the rich text capabilities.

If the database field does not include text formatting information, consider using a TDBMemo object or a TDBEdit object instead.

If the application doesn’t require the data-aware capabilities of TDBRichEdit, use a rich text edit control (TRichEdit) instead, to conserve system resources.


TDBRichEdit properties

TDBRichEdit	Alphabetically	Legend

In TDBRichEdit

AutoDisplay

DataField

DataSource

Field

ReadOnly

Derived from TCustomRichEdit

DefAttributes

DefaultConverter

HideScrollBars

HideSelection

PageRect

Paragraph

PlainText

SelAttributes

SelLength

SelStart

SelText

Derived from TCustomMemo

Alignment

CaretPos

Lines

ScrollBars

WantReturns

WantTabs

WordWrap

Derived from TCustomEdit

BorderStyle

CanUndo

MaxLength

Modified

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBRichEdit properties

TDBRichEdit	By object	Legend

Align

Alignment

AutoDisplay

BorderStyle

BoundsRect

Brush

CanUndo

CaretPos

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataField

DataSource

DefAttributes

DefaultConverter

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Handle

Height

HelpContext

HideScrollBars

HideSelection

Hint

ImeMode

ImeName

Left

Lines

MaxLength

Modified

Name

Owner

PageRect

Paragraph

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PlainText

PopupMenu

ReadOnly

ScrollBars

SelAttributes

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

WantReturns

WantTabs

Width

WindowProc

WordWrap


TDBRichEdit::AutoDisplay

TDBRichEdit	See also

Determines whether to automatically display the contents of the memo field in the rich edit control.

__property bool AutoDisplay = {read=FAutoDisplay, write=SetAutoDisplay, default=1};

Description

If AutoDisplay is true, the rich edit control automatically displays new data when the underlying BLOB field changes (such as when moving to a new record).

If AutoDisplay is false, the control shows only the field name whenever the underlying BLOB field changes. To display the data, the user can double-click on the control or select it and press Enter.

The effect of AutoDisplay is not purely cosmetic. The data shown by the TDBRichEdit object is the value of the Text property. When AutoDisplay is false, if the data changes, the value of the Text property changes to the name of the field. Thus, if AutoDisplay is false, applications should be cautious about using the value of the Text property to ascertain the value of the underlying field.

Calling the LoadMemo method causes Text to update to the current value of the BLOB field. This change will also be reflected in the appearance of the control on screen.

Change the value of AutoDisplay to false if the automatic loading of BLOB fields seems to take too long.

Note:	AutoDisplay only applies to BLOB fields. If the control is bound to another type of text field, AutoDisplay has no effect.


TDBRichEdit::DataField

TDBRichEdit	See also

Specifies the field from which the rich edit control displays data.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Use DataField to bind the rich edit control to a field in the dataset. To fully specify a database field, both the dataset and the field within that dataset must be defined. The DataSource property of the rich edit control specifies the dataset which contains the DataField.


TDBRichEdit::DataSource

TDBRichEdit	See also

Links the rich edit control to the dataset that contains the field it represents.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use DataSource to link the rich edit control to a dataset in which the data can be found. To fully specify a database field for the edit control, both the dataset and a field within that dataset must be defined. Use the DataField property to specify the particular field within the dataset.


TDBRichEdit::Field

TDBRichEdit	See also

Indicates the TField object for the database field the rich edit control represents.

__property Db::TField* Field = {read=GetField};

Description

Read Field to get direct access to the contents and properties of the database field without going through the edit window. Use Field to change the contents of the database field programmatically. Use the Text property instead if you want to change the contents of the edit window without immediately posting the changes to the dataset. Changing the Text property allows the user to cancel the changes.


TDBRichEdit::ReadOnly

TDBRichEdit	See also

Determines whether the user can use the rich database edit control to change the value of the field in the current record.

__property bool ReadOnly = {read=GetReadOnly, write=SetReadOnly, default=0};

Description

Set ReadOnly to true to prevent the user from changing the contents of the database field. When ReadOnly is true, the edit control is used only to display the contents of the field. If ReadOnly is false, the user can change the field's value as long as the dataset is in edit mode.


TDBRichEdit events

TDBRichEdit	Alphabetically	Legend

Derived from TCustomRichEdit

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBRichEdit events

TDBRichEdit	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange

OnStartDrag


TDBRichEdit methods

TDBRichEdit	Alphabetically	Legend

In TDBRichEdit

~TDBRichEdit

Change

KeyDown

KeyPress

LoadMemo

Notification

TDBRichEdit

Derived from TCustomRichEdit

Clear

FindText

GetSelTextBuf

Print

RegisterConversionFormat

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBRichEdit methods

TDBRichEdit	By object	Legend

~TDBRichEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

FindText

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

KeyPress

LoadMemo

MethodAddress

MethodName

NewInstance

Notification

PaintTo

PasteFromClipboard

Perform

Print

Realign

Refresh

RegisterConversionFormat

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TDBRichEdit

Undo

Update

UpdateControlState


TDBRichEdit::Change

TDBRichEdit	See also

Keeps track of the fact that the text has been modified, before letting the inherited method call the OnChange event handler if it is assigned.

DYNAMIC void __fastcall Change(void);

Description

Applications cannot call this protected method directly. It is triggered automatically by Windows’ events. Change responds to these events by internally keeping track of the fact that the text has been modified. This information can then be used to know whether there are any changes to post to the dataset or to remove if the user requests a reset.

Change also calls the inherited method, which calls the OnChange event handler if it is assigned.


TDBRichEdit::TDBRichEdit

TDBRichEdit	See also

Creates an instance of TDBRichEdit.

__fastcall virtual TDBRichEdit(Classes::TComponent* AOwner);

__fastcall TDBRichEdit(HWND ParentWindow) : Comctrls::TCustomRichEdit(ParentWindow) { }

Description

Do not call TDBRichEdit directly when creating a DB rich edit control at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TDBRichEdit object. TDBRichEdit objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TDBRichEdit object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TDBRichEdit object in a non-VCL window. This syntax is used when the DB rich edit control is implemented as an ActiveX control that is embedded in a non-VCL window.

After allocating and initializing a generic rich edit object, TDBRichEdit

•	Sets ReadOnly to true.

•	Sets AutoDisplay to true.

•	Creates and initializes the helper objects needed to link to a dataset.


TDBRichEdit::~TDBRichEdit

TDBRichEdit	See also

Destroys an instance of TDBRichEdit.

__fastcall virtual ~TDBRichEdit(void);

Description

Do not call ~TDBRichEdit directly in an application. Instead, use the delete keyword, which calls ~TDBRichEdit control indirectly.

~TDBRichEdit frees the helper objects of the TDBRichEdit.


TDBRichEdit::KeyDown

TDBRichEdit	See also

Supplements the inherited method to drive the dataset into edit mode when the user presses Del or Shift+Insert.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

KeyDown first calls the inherited method, which calls the OnKeyDown event handler. KeyDown next attempts to put the dataset into an editing state when the user types Del or Shift+Insert. Derived classes can override KeyDown to handle additional key combinations, but the inherited method should always be called.

Note:	Applications cannot call this protected method directly. It is called automatically in response to Windows events.


TDBRichEdit::KeyPress

TDBRichEdit	See also

Supplements the inherited method to handle any keystrokes that alter the state of the edit control.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

KeyPress first calls the inherited method, which calls the OnKeyPress event handler. Next, KeyPress checks the value of the key, and throws it away if it is not a valid character for the field type, or if there is no link to a database field. Valid characters cause KeyPress to attempt to put the dataset into edit mode.

Pressing the Escape key causes KeyPress to throw away all unposted edits. Pressing the Pause key causes KeyPress to call LoadMemo to load the value of the memo field associated with the rich edit control.

Note:	Applications cannot call this protected method directly. It is called automatically in response to Windows events.


TDBRichEdit::LoadMemo

TDBRichEdit	See also

LoadMemo loads the memo BLOB from the field in the database into the rich edit control.

void __fastcall LoadMemo(void);

Description

LoadMemo allows an application to control when the rich edit control displays the contents of the memo field. Use LoadMemo to update the text in the rich edit control to the value of the field in the current record. LoadMemo only works with BLOB fields when the AutoDisplay property is false, so that the value of the field is not loaded automatically.


TDBRichEdit::Notification

TDBRichEdit	See also

Overrides the inherited method to respond to opRemove notifications on the DataSource.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

After calling the inherited method, Notification checks whether the notification indicates the removal of the DataSource. If so, Notification sets the DataSource property to NULL.

Derived classes can override Notification method to handle additional notifications, but the inherited method should be always be called.

Note:	Notification is a protected method. Applications cannot call it directly.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMemo

TCustomRichEdit


 TDBText

Hierarchy	Properties	Methods	Events	See also

TDBText represents a data-aware control that displays the value of a field on a form.

Unit

dbctrls

Description

Use TDBText to display the contents of a field in the current record of a dataset on a form. Field values displayed by database text controls cannot be modified by the user using the text control. To allow the user to edit the field value, use TDBEdit or TDBMemo instead.

If the application doesn’t require the data-aware capabilities of TDBText, use the label component (TLabel) or the static text component (TStaticText) instead to conserve system resources.


TDBText properties

TDBText	Alphabetically	Legend

In TDBText

AutoSize

DataField

DataSource

Field

Derived from TCustomLabel

Alignment

Transparent

WordWrap

Derived from TGraphicControl

Canvas

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDBText properties

TDBText	By object	Legend

Align

Alignment

AutoSize

BoundsRect

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DataField

DataSource

DesignInfo

DragCursor

DragMode

Enabled

Field

Font

Height

Hint

Left

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Tag

Top

Transparent

VCLComObject

Visible

Width

WindowProc

WordWrap


TDBText::AutoSize

TDBText	See also

Determines whether the database text control automatically resizes to the width and length of the current string.

__property AutoSize;

Description

Use AutoSize to make the database text control adjust its size automatically so the client area accommodates the height and width of the field value. When AutoSize is false, the control is fixed in size. When AutoSize is true, the size of the control is readjusted whenever its caption changes. The size of the control is also readjusted when the Font property changes.

When WordWrap is true, the width of the database text control is fixed. If AutoSize is also true, changes to the field value cause the control to change in height. When AutoSize is true and WordWrap is false, the height of the control is determined by the font, and changes to the field value cause the control to change in width.


TDBText::DataField

TDBText	See also	Example

Specifies the field whose value is displayed by the database text control.

__property System::AnsiString DataField = {read=GetDataField, write=SetDataField};

Description

Use DataField to bind the database text control to a field in the dataset. To fully specify a database field, both the dataset and the field within that dataset must be defined. The DataSource property of the control specifies the dataset which contains the DataField.


TDBText::DataSource

TDBText	See also	Example

Links the text control to the dataset that contains the field it represents.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use DataSource to link the database text control to a dataset in which the data can be found. To fully specify a database field for the control, both the dataset and a field within that dataset must be defined. Use the DataField property to specify the particular field within the dataset.


TDBText::Field

TDBText	See also

Indicates the TField object for the database field the database text control represents.

__property Db::TField* Field = {read=GetField};

Description

Use the Field object to change the value of the data in the field programmatically.


TDBText events

TDBText	Alphabetically	Legend

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBText events

TDBText	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDBText methods

TDBText	Alphabetically

In TDBText

~TDBText

TDBText

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDBText methods

TDBText	By object

~TDBText

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TDBText

Update


TDBText::TDBText

TDBText	See also

Creates an instance of TDBText.

__fastcall virtual TDBText(Classes::TComponent* AOwner);

Description

Call TDBText indirectly, using the new keyword, to instantiate a TDBText object at runtime. For TDBText objects placed on forms or data modules at design time, TDBText is called automatically.

After calling the parent object's constructor to allocate and initialize a generic label object, TDBText

•	Adds csReplicatable to ControlStyle.

•	Sets AutoSize to false.

•	Creates and initializes the helper objects needed to link to a dataset.


TDBText::~TDBText

TDBText	See also

Destroys an instance of TDBText.

__fastcall virtual ~TDBText(void);

Description

Do not call ~TDBText directly in an application. Instead, call delete.

~TDBText frees the helper objects of the TDBText before calling the parent object's destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl

TCustomLabel


 TDdeClientConv

Hierarchy	Properties	Methods	Events	See also

TDdeClientConv represents a DDE conversation with a DDE server application.

Unit

ddeman

Description

Use TDdeClientConv in conjunction with a TDdeClientItem object to enable an application to act as a DDE client. TDdeClientConv provides many properties, events, and methods that provide services to

•	Link to a specified DDE server with a specified DDE topic.

•	Send data or macro commands to the DDE server after a link has been established.

•	Specify a format for the data that is sent to the DDE server.

•	Allow event handlers to respond when the DDE link is opened or closed.

TDdeClientItem objects are associated with a TDdeClientConv by setting their DdeConv property.


TDdeClientConv properties

TDdeClientConv	Alphabetically	Legend

In TDdeClientConv

ConnectMode

Conv

DataMode

DdeFmt

DdeService

DdeTopic

FormatChars

ServiceApplication

WaitStat

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDdeClientConv properties

TDdeClientConv	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConnectMode

Conv

DataMode

DdeFmt

DdeService

DdeTopic

DesignInfo

FormatChars

Name

Owner

ServiceApplication

Tag

VCLComObject

WaitStat


TDdeClientConv::ConnectMode

TDdeClientConv	See also	Example

Determines whether the link to the DDE server is established automatically when the form is opened.

enum TDataMode { ddeAutomatic, ddeManual };

__property TDataMode ConnectMode = {read=FConnectMode, write=SetConnectMode, default=0};

Description

Use ConnectMode to change the way a DDE conversation is established. If ConnectMode is ddeAutomatic, the link is established when it is defined by SetLink. If ConnectMode is ddeManual, the application must call the OpenLink method or the PasteLink method to establish the DDE conversation.


TDdeClientConv::Conv

TDdeClientConv	See also

Indicates the handle for the current DDE conversation.

__property int Conv = {read=FConv, nodefault};

Description

Read Conv to get a handle to the DDE conversation when it is required for a Windows API function call. Conv is available once a DDE conversation has been established by OpenLink or PasteLink.


TDdeClientConv::DataMode

TDdeClientConv	See also

Governs whether portions of the DDE conversation execute automatically.

enum TDataMode { ddeAutomatic, ddeManual };

__property TDataMode DataMode = {read=FDataMode, write=FDataMode, nodefault};

Description

DataMode is not implemented for TDdeClientConv. Derived objects can use this property to automatically execute portions of a DDE conversation, such as a RequestData or PokeData call.

Note:	To determine the way the DDE conversation is established, use ConnectMode instead.


TDdeClientConv::DdeFmt

TDdeClientConv	See also

Represents the clipboard format used for submitting or requesting a data item.

__property int DdeFmt = {read=FDdeFmt, nodefault};

Description

Use DdeFmt to specify the format of DDE data items when it has not been specified by the server.


TDdeClientConv::DdeService

TDdeClientConv	See also	Example

Specifies the DDE server application to be linked to a DDE client.

__property System::AnsiString DdeService = {read=FDdeService, write=SetDdeService};

Description

Use DdeService to specify the server application to link to. Typically, DdeService is the file name (with path, if necessary) of the DDE server application's main executable file without the .EXE extension. If the DDE server is an C++Builder application, DdeService is the project name without the .DPR or .EXE extension. For example, to link to a TDdeServerConv component in PROJ1.DPR, set DdeService to PROJ1.

At design time, specify DdeService by typing the DDE server application name in the object inspector or by choosing Paste Link in the DDE Info dialog box. To establish a link at runtime, specify the service and topic with the SetLink method.

Note:	The necessary value for DdeService depends on the individual server application. See the documentation of the DDE server application for specific information about how to specify the server application.


TDdeClientConv::DdeTopic

TDdeClientConv	See also 	Example

Specifies the topic of a DDE conversation

__property System::AnsiString DdeTopic = {read=FDdeTopic, write=SetDdeTopic};

Description

Use DdeTopic to indicate the server-defined topic name of the DDE conversation. Typically, DdeTopic is a file name (with path, if necessary) used by the server application. If the DDE server is a C++Builder application, by default DdeTopic is the caption of the form containing the linked component. If the DDE client is linked to a TDdeServerConv component, DdeTopic is the name of the server conversation component rather than the form caption.

At design time, specify DdeTopic either by typing the DdeTopic name in the object inspector or by choosing Paste Link in the DDE Info dialog box. To establish a link at runtime, specify the service and topic with the SetLink method.

Note:	The server application defines the topic names available for a DDE conversation. See the documentation for the DDE server application for specific information about the names of available topics.


TDdeClientConv::FormatChars

TDdeClientConv	See also	Example

Determines if certain characters are filtered out of text data transferred from a DDE server application.

__property bool FormatChars = {read=FFormatChars, write=SetFormatChars, default=0};

Description

Use FormatChars with DDE server applications that transfer backspaces, linefeeds, carriage returns, and tabs with the text data. These formatting characters can cause incorrect spacing, line breaks, or characters in the DDE client data. To prevent the formatting characters from interfering with the formatting of the client data, set FormatChars to false. To include the formatting characters sent by the DDE server, set FormatChars to true.


TDdeClientConv::ServiceApplication

TDdeClientConv	See also	Example

Specifies the main executable file name (with path, if necessary) of a DDE server application, without the .EXE extension.

__property System::AnsiString ServiceApplication = {read=FAppName, write=FAppName};

Description

Set ServiceApplication to the name of the server application. Typically, this is the same value as the DdeService property. Sometimes, however, DdeService is a value other than the DDE server application's executable file name.

If the server application is not running when the TDdeClientConv tries to establish a DDE conversation, OpenLink uses the ServiceApplication property to launch the server.


TDdeClientConv::WaitStat

TDdeClientConv	See also

Indicates whether the server is in the process of servicing a DDE macro that prohibits asynchronous DDE transactions.

__property bool WaitStat = {read=FWaitStat, nodefault};

Description

Read WaitStat to learn whether a DDE transaction can be started. When WaitStat is true, the server is processing the last macro, and attempts to execute a macro, request data, or poke data will fail. When WaitStat is false, the server is free to execute the next transaction in the DDE conversation.


TDdeClientConv events

TDdeClientConv	Alphabetically	Legend

In TDdeClientConv

OnClose

OnOpen


TDdeClientConv events

TDdeClientConv	By object	Legend

OnClose

OnOpen


TDdeClientConv::OnClose

TDdeClientConv	See also 	Example

Occurs when the DDE conversation terminates.

__property Classes::TNotifyEvent OnClose = {read=FOnClose, write=FOnClose};

Description

Write an OnClose event handler to take specific action when the DDE conversation ends. The DDE conversation will end if the server terminates the conversation, if the link is closed or changed, or if the TDdeClientConv object is destroyed.


TDdeClientConv::OnOpen

TDdeClientConv	See also 	Example

Occurs immediately after the DDE link to the server has been established.

__property Classes::TNotifyEvent OnOpen = {read=FOnOpen, write=FOnOpen};

Description

Write an OnOpen event handler to take specific action whenever a link is established to the DDE server. The DDE link is established by the OnOpen method or the PasteLink method. SetLink will also establish a DDE link if the ConnectMode is ddeAutomatic. OnOpen will not be called if the link fails, such as when the server application can’t be launched.


TDdeClientConv methods

TDdeClientConv	Alphabetically

In TDdeClientConv

~TDdeClientConv

CloseLink

ExecuteMacro

ExecuteMacroLines

OpenLink

PasteLink

PokeData

PokeDataLines

RequestData

SetLink

StartAdvise

TDdeClientConv

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDdeClientConv methods

TDdeClientConv	By object

~TDdeClientConv

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CloseLink

DefaultHandler

DestroyComponents

Destroying

Dispatch

ExecuteMacro

ExecuteMacroLines

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

OpenLink

PasteLink

PokeData

PokeDataLines

RemoveComponent

RequestData

SafeCallException

SetLink

StartAdvise

TDdeClientConv


TDdeClientConv::CloseLink

TDdeClientConv	See also	Example

Terminates an ongoing DDE conversation.

void __fastcall CloseLink(void);

Description

Use CloseLink when all communication with the DDE server is finished. After a link is closed, no DDE communication can take place between the DDE client and server until another link is opened.


TDdeClientConv::TDdeClientConv

TDdeClientConv	See also

Creates an instance of TDdeClientConv.

__fastcall virtual TDdeClientConv(Classes::TComponent* AOwner);

Description

Do not call TDdeClientConv directly to create an instance of TDdeClientConv. Instead, use the new keyword to obtain an indirect reference to a newly created TDdeClientConv object. After calling the parent object's constructor, TDdeClientConv creates the helper objects used to manage individual DDE client items.


TDdeClientConv::~TDdeClientConv

TDdeClientConv	See also

Destroys an instance of TDdeClientConv.

__fastcall virtual ~TDdeClientConv(void);

Description

Do not call ~TDdeClientConv directly in an application. Instead, use the delete keyword, which takes an indirect reference to a TDdeClientConv object.

~TDdeClientConv closes the link to the server and frees up all helper objects before calling the parent object's destructor.


TDdeClientConv::ExecuteMacro

TDdeClientConv	See also 	Example

Sends a macro command string to the DDE server application.

bool __fastcall ExecuteMacro(char * Cmd, bool WaitFlg);

Description

Call ExecuteMacro to send a single macro command to the server application. To send multiple macro commands, use ExecuteMacroLines instead. ExecuteMacro returns true if the macro was successfully passed to the DDE server application. If ExecuteMacro was unable to send a command string, ExecuteMacro returns false.

Cmd is a null-terminated string that contains the macro to be executed by the DDE server application. The actual value of Cmd depends on the DDE server application. See the documentation of the DDE server application for the command strings it will accept.

WaitFlg determines if this DDE client should wait until the DDE server application finishes executing the macro before allowing another DDE transaction to succeed. If WaitFlg is set to true, subsequent calls to ExecuteMacro, ExecuteMacroLines, PokeData, PokeDataLines, and RequestData will fail until the DDE server application completes the macro.

Attempting to execute a macro or poke data before a DDE server application completes a currently executing macro may cause the executing macro to fail or to produce unpredictable results. See the documentation of the DDE server application for the results of sending command strings or poking data before macro execution has completed.

Note:	ExecuteMacro returns true if the macro command was successfully passed to the DDE server. A true value does not ensure that the macro command will execute successfully once it has been accepted by the server.


TDdeClientConv::ExecuteMacroLines

TDdeClientConv	See also	Example

Sends a list of several macro commands to a DDE server application.

bool __fastcall ExecuteMacroLines(Classes::TStrings* Cmd, bool WaitFlg);

Description

Call ExecuteMacroLines to send several macro commands to the server application. To send a single macro command, use ExecuteMacro instead. ExecuteMacroLines returns true if the macro list was successfully passed to the DDE server application. If ExecuteMacroLines is unable to send a list of command strings, it returns false.

Cmd contains the list of macros to be executed by the DDE server application. WaitFlg determines if this DDE client should wait until the DDE server application finishes executing all the macros before allowing another DDE transaction to be sent. If WaitFlg is set to true, subsequent calls to ExecuteMacro, ExecuteMacroLines, PokeData, PokeDataLines, and RequestData will fail until the DDE server application completes all of the macros.


TDdeClientConv::OpenLink

TDdeClientConv	See also 	Example

Initiates a new DDE conversation.

bool __fastcall OpenLink(void);

Description

Call OpenLink to establish a new DDE conversation with the DdeService. If the server application is not running, OpenLink will launch the ServiceApplication. If the conversation is successfully opened, an OnOpen event occurs and OpenLink returns true. If the conversation isn't successfully opened, OpenLink returns false.

Note:	If ConnectMode is ddeAutomatic, OpenLink is called automatically when the DdeTopic and DdeService are specified by SetLink.


TDdeClientConv::PasteLink

TDdeClientConv	See also

Opens a DDE conversation with the current Clipboard object.

bool __fastcall PasteLink(void);

Description

Call PasteLink to establish a DDE link to an object on the Clipboard. PasteLink sets the DdeTopic or DdeService properties from the Clipboard. PasteLink returns true if the link is successfully established.


TDdeClientConv::PokeData

TDdeClientConv	See also 	Example

Sends data to a DDE server application.

bool __fastcall PokeData(const System::AnsiString Item, char *Data);

Description

Use PokeData to transfer text data to a DDE server that supports poked data. Item specifies the linked item in the DDE server. Data is a null-terminated string that specifies the text data to transfer.

The value of the DDE item depends on the linked DDE server application. Item is typically a selectable portion of text, such as a spreadsheet cell or a database field in an edit box. If the DDE server is an C++Builder application, Item is the name of the linked DDE server component.

The usual direction of data flow is from the DDE server to the DDE client application. Some DDE server applications won't accept poked data. PokeData returns true if the data was successfully transferred, false if the data was not successfully transferred.

To poke a string list rather than a single string, use the PokeDataLines method.

Note:	If either the ExecuteMacro or ExecuteMacroLines method was called with its WaitFlg parameter set to true, PokeData will automatically fail until the server application has completed executing the macro. The WaitStat property indicates when PokeData will attempt to poke data to the server.


TDdeClientConv::PokeDataLines

TDdeClientConv	See also 	Example

Sends multiple lines of data to a DDE server application.

bool __fastcall PokeDataLines(const System::AnsiString Item, Classes::TStrings* Data);

Description

Use PokeDataLines to transfer multiple lines of text data to a DDE server that supports poked data. Item specifies the linked item in the DDE server. Data is a set of strings that specifies the text data to transfer.

The value of the DDE item depends on the linked DDE server application. Item is typically a selectable portion of text, such as a spreadsheet cell or a database field in an edit box. If the DDE server is an C++Builder application, Item is the name of the linked DDE server component.

The usual direction of data flow is from the DDE server to the DDE client application. Some DDE server applications won't accept poked data. PokeData returns true if the data was successfully transferred, false if the data was not successfully transferred.

To poke a single string rather than a string list, use the PokeData method.

Note:	If either the ExecuteMacro or ExecuteMacroLines method was called with its WaitFlg parameter set to true, PokeData will automatically fail until the server application has completed executing the macro. The WaitStat property indicates when PokeData will attempt to poke data to the server.


TDdeClientConv::RequestData

TDdeClientConv	See also 	Example

Requests data from a DDE server.

char* __fastcall RequestData(const System::AnsiString Item);

Description

Call RequestData to send a request to the DDE server for the data named by Item. RequestData returns the value of the named DDE server item.

Note:	RequestData automatically allocates memory to store the returned data, but applications must dispose of this string after processing it. This is done with the StrDispose procedure.

If the DDE server contains DDE items that can be continually updated, data can be received and updated automatically by creating TDdeClientItem objects for those items.

The value of the DDE item depends on the linked DDE server application. Item is typically a selectable portion of text, such as a spreadsheet cell or a database field in an edit box. If the DDE server is an C++Builder application, Item is the name of the linked DDE server component.

Note:	See the documentation for the DDE server application for specific information about specifying a DDE item.


TDdeClientConv::SetLink

TDdeClientConv	See also 	Example

Specifies the service and topic of a DDE conversation and attempts to open the link if ConnectMode is ddeAutomatic.

bool __fastcall SetLink(const System::AnsiString Service, const System::AnsiString Topic);

Description

Call SetLink to fully specify a DDE conversation. If ConnectMode is ddeManual, calling SetLink is equivalent to setting the DdeTopic and DdeService properties, and clearing all data from any associated TDdeClientItem objects. If ConnectMode is ddeAutomatic, SetLink opens the link to the DDE server as well.

The Service and Topic parameters specify the values for the DdeTopic and DdeService properties, respectively.


TDdeClientConv::StartAdvise

TDdeClientConv	See also

Starts an advise loop for all of the TDdeClientItems associated with the current DDE conversation.

bool __fastcall StartAdvise(void);

Description

Call StartAdvise to start an advise loop for all of the TDdeClientItems associated with the current DDE conversation. StartAdvise returns true if loop startup is successful.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


 TDdeClientItem

Hierarchy	Properties	Methods	Events	See also

TDdeClientItem defines an item in a DDE conversation.

Unit

ddeman

Description

Use TDdeClientItem in conjunction with TDdeClientConv to enable an application to act as a DDE client. A DDE client item specifies a single item supported by a DDE server. A single TDdeClientConv object may be associated with multiple client items. If the DDE client conversation has established a link with a DDE server, the server will automatically and continually update all client items until the conversation is terminated.


TDdeClientItem properties

TDdeClientItem	Alphabetically	Legend

In TDdeClientItem

DdeConv

DdeItem

Lines

Text

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDdeClientItem properties

TDdeClientItem	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DdeConv

DdeItem

DesignInfo

Lines

Name

Owner

Tag

Text

VCLComObject


TDdeClientItem::DdeConv

TDdeClientItem	See also

Specifies the DDE client conversation to associate with the DDE client item.

__property TDdeClientConv* DdeConv = {read=FDdeClientConv, write=SetDdeClientConv};

Description

Set DdeConv to associate the DDE client item with a DDE client conversation. The value of DdeConv is the DDE client conversation object that defines the DDE conversation. The DdeConv establishes the link to the server that provides the Text for the DDE client item.


TDdeClientItem::DdeItem

TDdeClientItem	See also 	Example

Specifies the item of a DDE conversation.

__property System::AnsiString DdeItem = {read=FDdeClientItem, write=SetDdeClientItem};

Description

Set the DdeItem property to the name of a DDE item supported by the DDE server. The value of DdeItem depends on the linked DDE server application. DdeItem is typically a selectable portion of text, such as a spreadsheet cell or a database field in an edit box. If the DDE server is a C++Builder application, DdeItem is the name of the linked DDE server item.

At design time, specify DdeItem by typing the item string in the object inspector. Alternately, DdeItem can be specified from the DDE conversation by pasting a link using the DDE Info dialog box, which is called by clicking the ellipsis (...) button for DdeService or DdeTopic in the object inspector. After choosing Paste Link in the DDE Info dialog box, choose the item from a list of possible items for DdeItem in the object inspector when link information is on the Clipboard.

Note:	See the documentation for the DDE server application for the specific information about specifying DDE items.


TDdeClientItem::Lines

TDdeClientItem	See also 	Example

Contains the text data to exchange in a DDE conversation.

__property Classes::TStrings* Lines = {read=FLines, write=SetLines};

Description

Read Lines to get the text that is updated by the DDE server application. Lines is updated automatically by the DDE server. When Lines is changed by the server, an OnChange event occurs.

Set the Lines property to poke data to the DDE server.

Lines corresponds to the Text property. Whenever the value of Lines or Text is updated, the other is also changed so that the first line of Lines is always equal to Text.

Note:	Lines of data can also be sent to the DDE server by calling the PokeDataLines method of the DDE client conversation.


TDdeClientItem::Text

TDdeClientItem	See also

Contains the text data to exchange in a DDE conversation.

__property System::AnsiString Text = {read=GetText, write=SetText};

Description

Read Text to get the text that is updated by the DDE server application. Text is updated automatically by the DDE server. When Text is changed by the server, an OnChange event occurs.

Set the Text property to poke data to the DDE server.

Text corresponds to the Lines property. Whenever the value of Lines or Text is updated, the other is also changed so that the first line of Lines is always equal to Text.

For text data longer than the 255 character limit of Text, use the Lines property.

Note:	Data can also be sent to the DDE server by calling the PokeData method of the DDE client conversation.


TDdeClientItem events

TDdeClientItem	Alphabetically	Legend

In TDdeClientItem

OnChange


TDdeClientItem events

TDdeClientItem	By object	Legend

OnChange


TDdeClientItem::OnChange

TDdeClientItem	See also 	Example

Occurs immediately after the DDE server updates the Lines property.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action when the DDE server updates the text for this DDE client item. The new value for the DDE client item can be found by reading the Lines or Text property.


TDdeClientItem methods

TDdeClientItem	Alphabetically

In TDdeClientItem

~TDdeClientItem

TDdeClientItem

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDdeClientItem methods

TDdeClientItem	By object

~TDdeClientItem

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TDdeClientItem


TDdeClientItem::TDdeClientItem

TDdeClientItem	See also

Creates an instance of TDdeClientItem.

__fastcall virtual TDdeClientItem(Classes::TComponent* AOwner);

Description

Do not call TDdeClientItem directly to instantiate a TDdeClientItem. Instead, use the new keyword to obtain an indirect reference to a newly instantiated TDdeClientItem at runtime. After calling the parent object's constructor, TDdeClientItem creates a helper object to manage the Lines property.


TDdeClientItem::~TDdeClientItem

TDdeClientItem	See also

Destroys an instance of TDdeClientItem.

__fastcall virtual ~TDdeClientItem(void);

Description

Do not call ~TDdeClientItem directly in an application. Instead, use the delete keyword which takes an indirect reference to a TDdeClientItem object.

~TDdeClientItem frees the memory associated with the Lines property before calling the parent object's destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


 TDdeServerItem

Hierarchy	Properties	Methods	Events	See also

TDdeServerItem defines the item of a DDE conversation.

Unit

ddeman

Description

Use TDdeServerItem by itself, or, optionally, with a TDdeServerConv object to enable an application to function as a DDE server. DDE clients link to an individual DDE server item by referring to the Name property. Once a link to a DDE client is established, the DDE server item can update the client to changes in the item data, or receive data that the DDE client pokes to the item.


TDdeServerItem properties

TDdeServerItem	Alphabetically	Legend

In TDdeServerItem

Fmt

Lines

ServerConv

Text

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDdeServerItem properties

TDdeServerItem	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Fmt

Lines

Name

Owner

ServerConv

Tag

Text

VCLComObject


TDdeServerItem.Fmt

TDdeServerItem	See also

Indicates the clipboard format the DDE client item uses to pass data to the DDE client.

__property int Fmt = {read=FFmt, nodefault};

Description

Set Fmt in an OnChange event handler to specify a clipboard format for the data that is passed to the DDE client if it is not text. The DDE data that is sent to the DDE client includes this format so that clients can correctly interpret the data. Read Fmt when the client pokes data to the DDE server item to determine the clipboard format the client used to format the data.


TDdeServerItem::Lines

TDdeServerItem	See also 	Example

Contains the data to exchange in a DDE conversation.

__property Classes::TStrings* Lines = {read=FLines, write=SetLines};

Description

Set Lines to the data the DDE server item sends to the DDE client. Whenever the Lines property changes, an OnChange event occurs and then the new value is sent to the DDE client. If the DDE server item accepts poked data, Lines receives the data whenever the DDE client pokes data to this item. When Lines is changed by a DDE client poking data, an OnPokeData event occurs after the OnChange event.

Usually Lines contains text, and setting Lines sets the Fmt property to CF_TEXT. However, C++Builder strings can contain non-text data. If Lines does not specify text data, Fmt must be changed to indicate the format of the data in an OnChange event handler.

Lines corresponds to the Text property. Whenever the value of Lines or Text is changed, the other is updated so that the first line of Lines is always equal to Text.


TDdeServerItem::ServerConv

TDdeServerItem

Specifies the DDE server conversation to associate with the DDE server item.

__property TDdeServerConv* ServerConv = {read=FServerConv, write=SetServerConv};

Description

Set ServerConv to associate the DDE server item with a DDE topic represented by the DDE server conversation. If ServerConv is not set, the DDE topic of the conversation is the value of the Caption property of the form containing the TDdeServerItem component.


TDdeServerItem::Text

TDdeServerItem	See also 	Example

Contains the data to exchange in a DDE conversation.

__property System::AnsiString Text = {read=GetText, write=SetText};

Description

Set Text to the data the DDE server item sends to the DDE client. Whenever the Text property changes, an OnChange event occurs and then the new value is sent to the DDE client. If the DDE server item accepts poked data, Text receives the data whenever the DDE client pokes data to this item. When Text is changed by a DDE client poking data, an OnPokeData event occurs after the OnChange event.

Usually Text contains text, and setting Text sets the Fmt property to CF_TEXT. However, AnsiStrings can contain non-text data. If Text does not specify text data, Fmt must be changed to indicate the format of the data in an OnChange event handler.

Text corresponds to the Lines property. Whenever the value of Lines or Text is changed, the other is updated so that the first line of Lines is always equal to Text.

If the data to be exchanged is greater than 255 characters, use Lines instead.


TDdeServerItem events

TDdeServerItem	Alphabetically	Legend

In TDdeServerItem

OnChange

OnPokeData


TDdeServerItem events

TDdeServerItem	By object	Legend

OnChange

OnPokeData


TDdeServerItem::OnChange

TDdeServerItem	See also

Occurs when the Lines property changes, before the changes have been sent to the DDE client.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action when the DDE server item is about to update the DDE client. The new value for the DDE client item can be found by reading the Lines or Text property.

If the value of Lines does not contain text data, an OnChange event handler must be assigned to change the value of Fmt. OnChange is called after Fmt gets set to CF_TEXT by setting the Lines property, but before the data gets sent to the client.


TDdeServerItem::OnPokeData

TDdeServerItem	See also 	Example

Occurs after a DDE client changes the value of the Lines property.

__property Classes::TNotifyEvent OnPokeData = {read=FOnPokeData, write=FOnPokeData};

Description

Write an OnPokeData event handler to take specific action when the DDE client pokes data to this DDE server item. The new value for the item can be found by reading the Lines or Text property.

When a DDE client pokes data to a DDE server items, the PokeData method is called. PokeData causes the following events.

1	First, the new value is assigned to the Lines (Text) property.

2	An OnChange event occurs.

3	The new value is sent back to the DDE client.

4	An OnPokeData event occurs.


TDdeServerItem methods

TDdeServerItem	Alphabetically

In TDdeServerItem

~TDdeServerItem

Change

CopyToClipboard

PokeData

TDdeServerItem

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDdeServerItem methods

TDdeServerItem	By object

~TDdeServerItem

Assign

Change

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyToClipboard

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

PokeData

RemoveComponent

SafeCallException

TDdeServerItem


TDdeServerItem::Change

TDdeServerItem	See also

Generates an OnChange event.

DYNAMIC void __fastcall Change(void);

Description

Call Change to trigger an OnChange event when not setting the Lines or Text property. Use Change in conjunction with the OnChange event to enable the DDE server item to exchange data that is not compatible with the strings used by the Lines and Text properties.


TDdeServerItem::CopyToClipboard

TDdeServerItem	See also

Copies the data specified in the Text or Lines property to the Windows Clipboard, along with DDE link information.

void __fastcall CopyToClipboard(void);

Description

Use CopyToClipboard to enable DDE clients to link to the DDE server item by executing an Edit | Paste Link command, or its equivalent in the command structure of the DDE client application.

CopyToClipboard can be used to create a DDE link at runtime only. To create a link at design time, select the TDdeServerItem object and choose Edit | Copy from the menu. Then, activate the DDE client application and paste the link according to the rules of the DDE client application. See the documentation for the DDE client application for specific information about pasting the link.


TDdeServerItem::TDdeServerItem

TDdeServerItem	See also

Creates an instance of TDdeServerItem.

__fastcall virtual TDdeServerItem(Classes::TComponent* AOwner);

Description

Do not call TDdeServerItem directly to instantiate a DDE server item. Instead, use the new keyword to obtain an indirect reference to a newly constructed DDE server item at runtime. \ TDdeServerItem objects placed on forms at design time are created automatically.

After calling the parent object's constructor, TDdeServerItem initializes the Fmt property to CF_TEXT, and creates a helper object to manage the Lines property.


TDdeServerItem::~TDdeServerItem

TDdeServerItem	See also

Destroys an instance of TDdeServerItem.

__fastcall virtual ~TDdeServerItem(void);

Do not call ~TDdeServerItem directly in an application. Instead, use the delete keyword which takes an indirect reference to a TDdeServerItem object.

~TDdeServerItem frees the memory associated with the Lines property before calling the parent object's destructor.


TDdeServerItem::PokeData

TDdeServerItem	See also

Processes data that has been poked to the DDE server item by a DDE client.

int __fastcall PokeData(int Data);

Description

Call PokeData to inform the DDE server item that the DDE conversation holds data that has been poked from a DDE client. Data is the DDE handle to the poked data.

PokeData does the following:

1	Uses the Data handle to obtain the data that was poked.

2	Sets the Lines property to the new data value.

3	Triggers an OnChange event.

4	Sends the new value of the data back to the DDE client.

5	Triggers an OnPokeData event.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


 TDdeServerConv

Hierarchy	Properties	Methods	Events	See also

TDdeServerConv represents a DDE topic of conversation with a DDE client.

Unit

ddeman

Description

Use TDdeServerConv to establish a DDE topic with a DDE client application. Individual items under the DDE topic are represented by TDdeServerItem objects. These items are linked to the DDE server conversation by setting their ServerConv property.

Using a TDdeServerConv component is optional. Without a TDdeServerConv object, the client can still enter into a DDE conversation and receive an update directly from a TDdeServerItem object. However, a DDE server conversation is required to handle any macros that the DDE client may send.

The Name property of the DDE server conversation provides the topic used by DDE clients to establish a link to the DDE server conversation. DDE server items that are not associated with a DDE server conversation use the Caption property of the form for the topic name. Use a TDdeServerConv object when establishing multiple DDE topics in a single form, or when the Caption of the form may not be unique or constant at runtime.


TDdeServerConv properties

TDdeServerConv	Alphabetically	Legend

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDdeServerConv properties

TDdeServerConv	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDdeServerConv events

TDdeServerConv	Alphabetically	Legend

In TDdeServerConv

OnClose

OnExecuteMacro

OnOpen


TDdeServerConv events

TDdeServerConv	By object	Legend

OnClose

OnExecuteMacro

OnOpen


TDdeServerConv::OnClose

TDdeServerConv	See also

Occurs when the DDE client terminates the DDE conversation.

__property Classes::TNotifyEvent OnClose = {read=FOnClose, write=FOnClose};

Description

Write an OnClose event handler to take specific action when the DDE conversation ends. The DDE conversation will end if the client terminates the conversation. It does not end if the TDdeServerConv object is destroyed. In that case, the DDE server items simply remove themselves from the DDE server conversation, and continue the link to the DDE client.

The Sender parameter is the DDE server conversation, not the DDE client.


TDdeServerConv::OnExecuteMacro

TDdeServerConv	See also 	Example

Occurs when the DDE client sends a macro to the DDE server conversation.

typedef void __fastcall (__closure *TMacroEvent)(System::TObject* Sender, Classes::TStrings* Msg);

__property TMacroEvent OnExecuteMacro = {read=FOnExecuteMacro, write=FOnExecuteMacro};

Description

Write an OnExecuteMacro event handler to implement a response to macros sent by the DDE client. The Sender parameter is the DDE server conversation. The Msg parameter gives the macro string to execute.


TDdeServerConv::OnOpen

TDdeServerConv	See also

Occurs immediately after the DDE link to the client has been established.

__property Classes::TNotifyEvent OnOpen = {read=FOnOpen, write=FOnOpen};

Description

Write an OnOpen event handler to take specific action whenever a link is established to a DDE client. The Sender parameter is the DDE server conversation, not the DDE client.


TDdeServerConv methods

TDdeServerConv	Alphabetically

In TDdeServerConv

~TDdeServerConv

ExecuteMacro

TDdeServerConv

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDdeServerConv methods

TDdeServerConv	By object

~TDdeServerConv

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

ExecuteMacro

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TDdeServerConv


TDdeServerConv::TDdeServerConv

TDdeServerConv	See also

Creates an instance of TDdeServerConv.

__fastcall virtual TDdeServerConv(Classes::TComponent* AOwner);

Description

Do not call TDdeServerConv directly to create an instance of TDdeServerConv at runtime. Instead, use the new keyword. TDdeServerConv objects placed on forms at design time are created automatically.


TDdeServerConv::~TDdeServerConv

TDdeServerConv	See also

Destroys an instance of TDdeServerConv.

__fastcall virtual ~TDdeServerConv(void);

Do not call ~TDdeServerConv directly in an application. Instead, use the delete keyword which takes an indirect reference to the TDdeServerConv object.

~TDdeServerConv removes the DDE server conversation topic from the application, but does not terminate any currently open DDE conversations. Instead, the DDE server items that were associated with the DDE server conversation become associated with the form instead, and continue their link to the DDE client.


TDdeServerConv::ExecuteMacro

TDdeServerConv	See also

Responds to macros sent by the DDE client.

int __fastcall ExecuteMacro(int Data);

Description

ExecuteMacro provides the only way for a C++Builder application to respond to macros sent by DDE clients. ExecuteMacro is called when the DDE client sends a Macro over the DDE link. Data is the handle to the DDE data that contains the macro.

ExecuteMacro retrieves the strings of the macro from Data, and calls the OnExecuteMacro event handler. If there is no OnExecuteMacro event handler, the macro is ignored. Whether or not there is an OnExecuteMacro event handler, the DDE client always receives notification that the macro was successfully transmitted, unless Data contains no macro.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


 TDecisionCube

Hierarchy	Properties	Methods	Events	See also

TDecisionCube maintains crosstabulated data that it provides to a TDecisionSource object.

Unit

mxdb

Description

Add a TDecisionCube object to a form or data module to allow an application to represent crosstabulated data. TDecisionCube analyzes the data from a source dataset into a multidimensional structure where each dimension corresponds to a field in the dataset over which information is summarized. Any dataset can be used as the source of a TDecisionCube object, but it is easiest to work with TDecisionQuery.

Usually, the summarized values are calculated by the dataset that is the source of the decision cubes. However, average values can be calculated internally by the Decision Cube instead.  Internally calculated averages have the advantage that they can be pivoted, subtotalled, and drilled-in correctly by Decision grids that display the data from the Decision Cube.

TDecisionCube introduces properties and methods that allow a crosstabulated data store to provide its data to a TDecisionSource object. Decision grids and Decision graphs do not retrieve data directly from the decision cube. They use a TDecisionSource object which represents a configuration of the dimensions from the TDecisionCube object.


TDecisionCube properties

TDecisionCube	Alphabetically	Legend

In TDecisionCube

Active

DesignState

Derived from TCustomDataStore

BinData

Capacity

CurrentSummary

DataSet

DimensionCount

DimensionMap

DimensionMapCount

MaxDimensions

MaxSummaries

ShowProgressDialog

SummaryCount

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDecisionCube properties

TDecisionCube	By object	Legend

Active

BinData

Capacity

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

CurrentSummary

DataSet

DesignInfo

DesignState

DimensionCount

DimensionMap

DimensionMapCount

MaxDimensions

MaxSummaries

Name

Owner

ShowProgressDialog

SummaryCount

Tag

VCLComObject


TDecisionCube::Active

TDecisionCube	See also

Specifies whether the decision cube can provide data.

__property bool Active = {read=CubeGetActive, write=CubeSetActive, nodefault};

Description

Read Active to determine whether the decision cube is ready to provide data to a decision control. Set Active to true to cause the decision cube to fetch and analyze data from the dataset specified in the DataSet property.

When Active is false, the decision cube is closed and the decision source can’t read data from the decision cube. When Active is true, data can be read from the decision cube.

Note:	The Active property cannot be set to true unless the dataset specified by the DataSet property is already active.


TDecisionCube::DesignState

TDecisionCube	See also

Specifies how much data is displayed by the decision cube at design time.

enum TCubeDataState { dsNoData, dsMetaData, dsDimensionData, dsAllData };

__property TCubeDataState DesignState = {read=FDesignState, write=SetDesignState, nodefault};

Description

Set DesignState to limit the amount of information that is provided when the decision cube is active at design time. Building the cache of the decision cube can be time and memory intensive.  Limiting the information the decision cube can supply at design time can improve design time performance when the decision cube has many dimensions or when the dimensions have many values.

DesignState has one of the following values:

Value	Meaning
dsNoData	The decision cube can’t be activated at design time.
dsMetaData	The decision cube provides the dimension captions, but no listing of values along the dimensions, and no summarized data.
dsDimensionData	The decision cube provides dimension captions, and the values of the dimension fields, but no summarized data.
dsAllData	The decision cube provides all possible data: dimension captions, the values of dimension fields, and summarized data.
Note:	The Value of DesignState can be changed at design time using the Decision Cube editor.


TDecisionCube events

TDecisionCube	Alphabetically	Legend

Derived from TCustomDataStore

AfterClose

AfterOpen

BeforeClose

BeforeOpen

OnLowCapacity

OnRefresh


TDecisionCube events

TDecisionCube	By object	Legend

AfterClose

AfterOpen

BeforeClose

BeforeOpen

OnLowCapacity

OnRefresh


TDecisionCube methods

TDecisionCube	Alphabetically

In TDecisionCube

~TDecisionCube

GetDetailSQL

GetSQL

ShowCubeDialog

TDecisionCube

Derived from TCustomDataStore

GetDimensionMemberCount

GetDimensionName

GetMemberAsString

GetMemberAsVariant

GetMemoryUsage

GetSummaryAsString

GetSummaryAsVariant

GetSummaryName

Refresh

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDecisionCube methods

TDecisionCube	By object

~TDecisionCube

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetDetailSQL

GetDimensionMemberCount

GetDimensionName

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMemberAsString

GetMemberAsVariant

GetMemoryUsage

GetNamePath

GetParentComponent

GetSQL

GetSummaryAsString

GetSummaryAsVariant

GetSummaryName

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Refresh

RemoveComponent

SafeCallException

ShowCubeDialog

TDecisionCube


TDecisionCube::TDecisionCube

TDecisionCube	See also

Creates an instance of TDecisionCube.

__fastcall virtual TDecisionCube(Classes::TComponent* AOwner);

Description

Call TDecisionCube indirectly, using the new keyword, to instantiate a decision cube at runtime. Decision cubes placed on a form or data module at design time are created automatically.

TDecisionCube allocates the memory for the decision cube and its helper objects and initializes the Active property to false and the DesignState property to dsAllData.


TDecisionCube::~TDecisionCube

TDecisionCube	See also

Destroys an instance of TDecisionCube.

__fastcall virtual ~TDecisionCube(void);

Description

Do not call the ~TDecisionCube method directly. Instead use the delete keyword.


TDecisionCube::GetDetailSQL

TDecisionCube	See also

Returns an SQL statement that can be used to generate the described subset of the data in the decision cube.

System::AnsiString __fastcall GetDetailSQL(Mxarrays::TSmallIntArray* ValueArray, System::AnsiString SelectList, bool bActive);

Description

Use the SQL statement returned by GetDetailSQL to generate a dataset that represents the records that gave rise to a subset of the values in the decision cube. The resulting query produces the records represented in the projection described by the ValueArray parameter. The dataset will include all fields that make up the dimensions of the decision cube, plus any fields listed in the SelectList parameter. The query does not include any summary values or grouping, such as must be imposed by the dataset of the decision cube.

Each entry in the ValueArray parameter corresponds to a dimension of the decision cube, where the first entry corresponds to the first dimension, the second entry corresponds to the second dimension, and so on. If the value of an entry in the value array is less than 0, all field values over that dimension are included in the new dataset. If the value of an entry in the value array is equal to or greater than 0, it is interpreted as the index of a value over the dimension field. When the ValueArray specifies a field value, the SQL statement restricts the dataset to records that match that value on the corresponding field of the original database table. Thus, ValueArray represents the dimension array with a set of drilled dimensions.

bActive specifies whether the ValueArray parameter includes inactive dimensions. Only active dimensions are included when bActive is true. Also when bActive is true, only the fields that correspond to active dimensions are included automatically in the SQL query.

The SelectList parameter is a list of comma delimited field names for the fields that are included in the result set of the SQL query. The query always includes the fields that correspond to the dimensions represented by the ValueArray parameter. If SelectList consists of a single asterisk (*), all the fields in the original dataset are included.


TDecisionCube::GetSQL

TDecisionCube	See also

Returns an SQL statement that can be used to generate the described subset of the data in the decision cube

System::AnsiString __fastcall GetSQL(Mxarrays::TSmallIntArray* ValueArray, bool bActive);

Description

Use the SQL statement returned by GetSQL to view the data that gave rise to a subset of the information in the decision cube. The resulting query produces a dataset containing the projection described by the ValueArray parameter. All the summaries of the current dataset are included in the resulting query.

Each entry in the ValueArray parameter corresponds to a dimension of the decision cube, where the first entry corresponds to the first dimension, the second entry corresponds to the second dimension, and so on. If the value of an entry in the value array is less than 0, all field values over that dimension are included in the new dataset. If the value of an entry in the value array is equal to or greater than 0, it is interpreted as the index of a value over the dimension field. When the ValueArray specifies a field value, the SQL statement restricts the dataset to records that match that value on the corresponding field of the original database table. Thus, ValueArray represents the dimension array with a set of drilled dimensions.

bActive specifies whether the ValueArray parameter includes inactive dimensions. Only active dimensions are included when bActive is true.

To further restrict the dataset so that it includes only a subset of the dimensions in the decision cube, use the GetDetailSQL method.


TDecisionCube::ShowCubeDialog

TDecisionCube	See also

Displays the Decision Cube editor.

void __fastcall ShowCubeDialog(void);

Description

Call ShowCubeDialog to allow the user to change the active dimensions of the data cube using the Decision Cube editor. ShowCubeDialog brings up the same dialog that appears when Decision Cube editor is selected from the pop-up menu of the decision cube component at design time.

The Decision Cube editor allows the user to make dimensions active or inactive and to change the names of dimensions. It also controls how much information is shown in a decision control at design time.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomDataStore


TDecisionGraph

Hierarchy	Properties	Methods	Events	See also

TDecisionGraph displays a graph of crosstabulated data.

Unit

mxgraph

Description

Use TDecisionGraph to put a decision graph in a form. Decision graphs chart a single summary that is calculated over a number of dimensions. The axes of the graph correspond to these dimensions, which are provided by a decision source object. By default, the first row dimension appears as the x axis and the first column dimension appears as the y axis.

The field that is summarized and the fields (dimensions) over which it is summarized can be changed dynamically at runtime to view any configuration of summary and dimensions chosen from the dimension map of a decision cube. Changes to the dimensions and summary can be initiated using a TDecisionPivot object.

TDecisionGraph publishes many of the properties, events, and methods inherited from TCustomDecisionGraph, but introduces no new behavior.

To present the crosstabulated data in a grid, use TDecisionGrid instead.


TDecisionGraph properties

TDecisionGraph	Alphabetically	Legend

Derived from TCustomDecisionGraph

DecisionSource

Derived from TChart

AllowPanning

AllowZoom

AnimatedZoom

AnimatedZoomSteps

BackImage

BackImageInside

BackImageMode

BottomWall

Foot

Gradient

LeftWall

PrintResolution

Title

Zoomed

Derived from TCustomChart

AxisVisible

BackColor

BottomAxis

BufferedDisplay

Chart3DPercent

ClipPoints

Frame

LeftAxis

Legend

MarginBottom

MarginLeft

MarginRight

MarginTop

MaxPointsPerPage

Monochrome

Page

RightAxis

ScaleLastPage

Series

SeriesList

TopAxis

View3d

View3dWalls

Derived from TCustomTeePanel

Canvas

Derived from TCustomPanel

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

Locked

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDecisionGraph properties

TDecisionGraph	By object	Legend

Align

AllowPanning

AllowZoom

AnimatedZoom

AnimatedZoomSteps

AxisVisible

BackColor

BackImage

BackImageInside

BackImageMode

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

BottomAxis

BottomWall

BoundsRect

Brush

BufferedDisplay

Canvas

Chart3DPercent

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ClipPoints

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DecisionSource

DesignInfo

DragCursor

DragMode

Enabled

Foot

Frame

Gradient

Handle

Height

HelpContext

Hint

Left

LeftAxis

LeftWall

Legend

Locked

MarginBottom

MarginLeft

MarginRight

MarginTop

MaxPointsPerPage

Monochrome

Name

Owner

Page

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

PrintResolution

RightAxis

ScaleLastPage

Series

SeriesList

ShowHint

Showing

TabOrder

TabStop

Tag

Title

Top

TopAxis

VCLComObject

View3d

View3dWalls

Visible

Width

WindowProc

Zoomed


TDecisionGraph events

TDecisionGraph	Alphabetically	Legend

Derived from TChart

OnAllowScroll

OnClickAxis

OnClickBackground

OnClickLegend

OnClickSeries

OnGetLegendPos

OnGetLegendRect

OnScroll

OnUndoZoom

OnZoom

Derived from TCustomChart

OnAfterDraw

OnGetAxisLabel

OnGetLegendText

OnGetNextAxisLabel

OnPageChange

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp


TDecisionGraph events

TCustomDecisionGraph	By object	Legend

OnAfterDraw

OnAllowScroll

OnClick

OnClickAxis

OnClickBackground

OnClickLegend

OnClickSeries

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnGetAxisLabel

OnGetLegendPos

OnGetLegendRect

OnGetLegendText

OnGetNextAxisLabel

OnMouseDown

OnMouseMove

OnMouseUp

OnPageChange

OnResize

OnScroll

OnUndoZoom

OnZoom


TDecisionGraph methods

TDecisionGraph	Alphabetically

In TDecisionGraph

~TDecisionGraph

TDecisionGraph

Derived from TChart

CalcClickedPart

CalcMetaBounds

ChartPrintRect

CopyToClipboardBitmap

CopyToClipboardMetafile

DrawToMetaCanvas

ExchangeSeries

FillSeriesSourceItems

FillValueSourceItems

GetEditorClass

IsScreenHighColor

NextPage

PreviousPage

Print

PrintLandscape

PrintOrientation

PrintPartial

PrintPartialCanvas

PrintPortrait

PrintRect

SaveToBitmapFile

SaveToMetafile

SaveToMetafileEnh

SaveToMetafileRect

SeriesDown

SeriesUp

TeeCreateMetafile

UndoZoom

ZoomPercent

ZoomRect

Derived from TCustomChart

ActiveSeriesLegend

AddSeries

BackWallRect

CalcSize3d

CalcSize3dWalls

ChartRegionRect

CheckDatasource

CheckPenWidth

ClipRectangle

Draw

FormattedLegend

FormattedValueLegend

FreeAllSeries

GetASeries

GetAxisSeries

GetFreeSeriesColor

GetLabelsSeries

InternalDraw

IsFreeSeriesColor

IsValidDataSource

MarkText

MaxMarkWidth

MaxTextWidth

MaxXValue

MaxYValue

MinXValue

MinYValue

NumPages

RemoveAllSeries

RemoveSeries

SeriesCount

SeriesTitleLegend

UnClipRectangle

XLabelText

Derived from TCustomTeePanel

CanvasChanged

DoHorizLine

DoLine

DoPolygon

DoRectangle

DoVertLine

FontCanvas

GetCursorPos

GetRectangle

GetWidthHeight

ReCalcWidthHeight

RotateLabel

SetBooleanProperty

SetBrushCanvas

SetColorProperty

SetDoubleProperty

SetIntegerProperty

SetInternalCanvas

SetLongintProperty

SetStringProperty

TeeCharHeight

TeeTextHeight

TeeTextOut

TeeTextWidth

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDecisionGraph methods

TDecisionGraph	By object

~TDecisionGraph

ActiveSeriesLegend

AddSeries

Assign

BackWallRect

BeginDrag

BringToFront

Broadcast

CalcClickedPart

CalcMetaBounds

CalcSize3d

CalcSize3dWalls

CanFocus

CanvasChanged

ChartPrintRect

ChartRegionRect

CheckDatasource

CheckPenWidth

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ClipRectangle

ContainsControl

ControlAtPos

CopyToClipboardBitmap

CopyToClipboardMetafile

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DoHorizLine

DoLine

DoPolygon

DoRectangle

DoVertLine

DragDrop

Dragging

Draw

DrawToMetaCanvas

EnableAlign

EndDrag

ExchangeSeries

FieldAddress

FillSeriesSourceItems

FillValueSourceItems

FindComponent

Focused

FontCanvas

FormattedLegend

FormattedValueLegend

Free

FreeAllSeries

FreeInstance

FreeNotification

FreeOnRelease

GetASeries

GetAxisSeries

GetCursorPos

GetEditorClass

GetFreeSeriesColor

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLabelsSeries

GetNamePath

GetParentComponent

GetRectangle

GetTabOrderList

GetTextBuf

GetTextLen

GetWidthHeight

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

InternalDraw

Invalidate

IsFreeSeriesColor

IsScreenHighColor

IsValidDataSource

MarkText

MaxMarkWidth

MaxTextWidth

MaxXValue

MaxYValue

MethodAddress

MethodName

MinXValue

MinYValue

NewInstance

NextPage

NumPages

PaintTo

Perform

PreviousPage

Print

PrintLandscape

PrintOrientation

PrintPartial

PrintPartialCanvas

PrintPortrait

PrintRect

Realign

ReCalcWidthHeight

Refresh

RemoveAllSeries

RemoveComponent

RemoveControl

RemoveSeries

Repaint

RotateLabel

SafeCallException

SaveToBitmapFile

SaveToMetafile

SaveToMetafileEnh

SaveToMetafileRect

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SeriesCount

SeriesDown

SeriesTitleLegend

SeriesUp

SetBooleanProperty

SetBounds

SetBrushCanvas

SetColorProperty

SetDoubleProperty

SetFocus

SetIntegerProperty

SetInternalCanvas

SetLongintProperty

SetStringProperty

SetTextBuf

Show

TDecisionGraph

TeeCharHeight

TeeCreateMetafile

TeeTextHeight

TeeTextOut

TeeTextWidth

UnClipRectangle

UndoZoom

Update

UpdateControlState

XLabelText

ZoomPercent

ZoomRect


TDecisionGraph::TDecisionGraph

TDecisionGraph

Creates a new TDecisionGraph object.

__fastcall virtual TDecisionGraph(Classes::TComponent* AOwner) : Mxgraph::TCustomDecisionGraph(AOwner) { }

__fastcall TDecisionGraph(HWND ParentWindow) : Mxgraph::TCustomDecisionGraph(ParentWindow) { }

Description

To create a decision graph at runtime, call TDecisionGraph indirectly, using the keyword new. Decision graphs placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the decision graph with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the decision graph in a non-VCL window. This syntax is used when the graph is implemented as an ActiveX control that is embedded in a non-VCL window.


TDecisionGraph::~TDecisionGraph

TDecisionGraph

~TDecisionGraph frees the memory associated with the TDecisionGraph object.

__fastcall virtual ~TDecisionGraph(void) { }

Description

Do not call ~TDecisionGraph directly. Instead, use the delete keyword on the object, which causes ~TDecisionGraph to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomPanel

TCustomTeePanel

TCustomChart

TChart

TCustomDecisionGraph


 TDecisionGrid

Hierarchy	Properties	Methods	Events	See also

TDecisionGrid presents crosstabulated data from a decision source in a grid format.

Unit

mxgrid

Description

Use TDecisionGrid to put a decision grid in a form. Decision grids present a single summary that is calculated over an arbitrary number of dimensions. The dimensions can appear as rows or columns in the grid, with the field values of the dimensions listed as labels along the top and left edges of the grid.

The field that is summarized and the fields (dimensions) over which it is summarized can be changed dynamically at runtime to view any configuration of summary and dimensions chosen from the dimension map of a decision cube. Changes to the dimensions and summary can be initiated by direct manipulation of the decision grid, or by using a TDecisionPivot object.

TDecisionGrid publishes many of the properties, events, and methods inherited from TCustomDecisionGrid, but introduces no new behavior.

To present the crosstabulated data in a chart, use TDecisionGraph instead.


TDecisionGrid properties

TDecisionGrid	Alphabetically	Legend

Derived from TCustomDecisionGrid

CaptionColor

CaptionFont

Cells

ColCount

DataColor

DataFont

DataSumColor

DecisionSource

DefaultColWidth

DefaultRowHeight

Dimensions

FixedCols

FixedRows

GridLineColor

GridLineWidth

LabelColor

LabelFont

LabelSumColor

Options

RowCount

ShowCubeEditor

Totals

Derived from TCustomGrid

BorderStyle

DefaultDrawing

ScrollBars

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDecisionGrid properties

TDecisionGrid	By object	Legend

Align

BorderStyle

BoundsRect

Brush

CaptionColor

CaptionFont

Cells

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ColCount

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DataColor

DataFont

DataSumColor

DecisionSource

DefaultColWidth

DefaultDrawing

DefaultRowHeight

DesignInfo

Dimensions

DragCursor

DragMode

Enabled

FixedCols

FixedRows

GridLineColor

GridLineWidth

Handle

Height

HelpContext

Hint

LabelColor

LabelFont

LabelSumColor

Left

Name

Options

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

RowCount

ScrollBars

ShowCubeEditor

ShowHint

Showing

TabOrder

TabStop

Tag

Top

Totals

VCLComObject

Visible

Width

WindowProc


TDecisionGrid events

TDecisionGrid	Alphabetically	Legend

Derived from TCustomDecisionGrid

OnDecisionDrawCell

OnDecisionExamineCell

OnTopLeftChanged

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDecisionGrid events

TDecisionGrid	By object	Legend

OnClick

OnDblClick

OnDecisionDrawCell

OnDecisionExamineCell

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag

OnTopLeftChanged


TDecisionGrid methods

TDecisionGrid	Alphabetically

In TDecisionGrid

~TDecisionGrid

TDecisionGrid

Derived from TCustomDecisionGrid

CellDrawState

CellValueArray

Notification

Derived from TCustomGrid

MouseCoord

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDecisionGrid methods

TDecisionGrid	By object

~TDecisionGrid

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CellDrawState

CellValueArray

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

MouseCoord

NewInstance

Notification

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDecisionGrid

Update

UpdateControlState


TDecisionGrid::TDecisionGrid

TDecisionGrid

Creates a new TDecisionGrid object.

__fastcall virtual TDecisionGrid(Classes::TComponent* AOwner) : Mxgrid::TCustomDecisionGrid(AOwner) { }

__fastcall TDecisionGrid(HWND ParentWindow) : Mxgrid::TCustomDecisionGrid(ParentWindow) { }

Description

To create a decision grid at runtime, call TDecisionGrid indirectly, using the keyword new. Decision grids placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the decision grid with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the decision grid in a non-VCL window. This syntax is used when the grid is implemented as an ActiveX control that is embedded in a non-VCL window.


TDecisionGrid::~TDecisionGrid

TDecisionGrid

~TDecisionGrid frees the memory associated with the TDecisionGrid object.

__fastcall virtual ~TDecisionGrid(void) { }

Description

Do not call ~TDecisionGrid directly. Instead, use the delete keyword on the object, which causes ~TDecisionGrid to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGrid

TCustomDecisionGrid


 TDecisionPivot

Hierarchy	Properties	Methods	Events	See also

TDecisionPivot allows the user to control the pivot state of a decision source.

Unit

mxpivsrc

Description

Add a decision pivot to a form to allow users to control the pivot state of decision graphs and decision grids. Decision pivots contain buttons that correspond to the active dimensions of a decision cube and a drop-down list box for choosing the current summary.

Pressing the dimension buttons opens or closes the dimensions, controlling whether the decision source provides detailed data values for those dimensions. Right-clicking the buttons of a decision pivot brings up a menu that allows users to control the drill state of a dimension. Drilled dimensions focus on a single value within the dimension. Dragging the buttons on a decision pivot rearranges the dimensions of the decision source into a new pivot configuration.

Note:	Do not use the Decision pivot to pivot, subtotal, or drill in on summaries that are not additive.  SUM and COUNT summaries are additive, AVERAGE (unless calculated by the Decision cube), MAX, and MIN are not.


TDecisionPivot properties

TDecisionPivot	Alphabetically	Legend

In TDecisionPivot

BorderStyle

BorderWidth

ButtonAutoSize

ButtonHeight

ButtonSpacing

ButtonWidth

DecisionSource

GroupLayout

Groups

GroupSpacing

Derived from TCustomPanel

Alignment

BevelInner

BevelOuter

BevelWidth

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDecisionPivot properties

TDecisionPivot	By object	Legend

Align

Alignment

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

BoundsRect

Brush

ButtonAutoSize

ButtonHeight

ButtonSpacing

ButtonWidth

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DecisionSource

DesignInfo

DragCursor

DragMode

Enabled

Font

GroupLayout

Groups

GroupSpacing

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TDecisionPivot::BorderStyle

TDecisionPivot	See also

Determines whether a line is drawn around the perimeter of the decision pivot.

enum TFormBorderStyle { bsNone, bsSingle, bsSizeable, bsDialog, bsToolWindow, bsSizeToolWin };

typedef TFormBorderStyle TBorderStyle;

__property Forms::TBorderStyle BorderStyle = {read=GetBorderStyle, write=SetBorderStyle, nodefault}

Description

Use BorderStyle to specify whether the decision pivot has a single line drawn around it. When BorderStyle is bsSingle, a single line is drawn around the panel outside of the outer bevel. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border

Don’t confuse the line drawn around the decision pivot with the BorderWidth property. The BorderWidth is the distance between the outer and inner bevels.


TDecisionPivot::BorderWidth

TDecisionPivot	See also

Specifies the distance, in pixels, between the outer and inner bevels.

typedef int TBorderWidth;

__property Extctrls::TBorderWidth BorderWidth = {read=GetBorderWidth, write=SetBorderWidth, nodefault};

Description

Use BorderWidth to specify how wide the border around the decision pivot should be. A value of 0 means no border should appear.

The border of the decision pivot is the area between the outer and inner bevels. It is visible only if the inner bevel is raised or lowered, but affects the inset of the controls in the pivot even if BevelInner is bvNone.

Don’t confuse the border of the pivot with line drawn around it. The line around the pivot is specified by the BorderStyle property.


TDecisionPivot::ButtonAutoSize

TDecisionPivot	See also

Specifies whether the dimension buttons resize automatically when the decision pivot resizes.

__property bool ButtonAutoSize = {read=FAutosize, write=SetAutoSize, nodefault};

Description

Set ButtonAutoSize to true to cause the dimension buttons to expand and contract automatically when the size of the decision pivot changes. Set ButtonAutoSize to false to specify fixed size buttons.

Note:	The value of ButtonAutoSize is ignored when GroupLayout is xtTopLeft.


TDecisionPivot::ButtonHeight

TDecisionPivot	See also

Specifies the height, in pixels, of the dimension buttons.

__property int ButtonHeight = {read=FControlHeight, write=SetControlHeight, nodefault};

Description

Use ButtonHeight to determine the Height of the dimension buttons. Do not set ButtonHeight when the ButtonAutoSize property is true. When ButtonAutoSize is true, the height of the buttons is reset automatically whenever the layout of the decision pivot changes.


TDecisionPivot::ButtonSpacing

TDecisionPivot	See also

Specifies the number of pixels that appear between dimension buttons.

__property int ButtonSpacing = {read=FSpacing, write=SetSpacing, nodefault};

Description

Set ButtonSpacing to control the spacing between the buttons in a single group. Increase ButtonSpacing to make a decision pivot look less crowded. Decrease ButtonSpacing to make the row and column groups look more compact.


TDecisionPivot::ButtonWidth

TDecisionPivot	See also

Specifies the width, in pixels, of the dimension buttons.

__property int ButtonWidth = {read=FControlWidth, write=SetControlWidth, nodefault};

Description

Use ButtonWidth to determine the Width of the dimension buttons. Do not set ButtonWidth when the ButtonAutoSize property is true. When ButtonAutoSize is true, the width of the buttons is reset automatically whenever the layout of the decision pivot changes.


TDecisionPivot::DecisionSource

TDecisionPivot	See also

Specifies the decision source object that the decision pivot controls.

__property Mxdb::TDecisionSource* DecisionSource = {read=FSource, write=SeTDecisionSource};

Description

Set DecisionSource to link the decision pivot to a decision source component. The controls in the decision pivot change the pivot state of the decision source.

The pivot state of the decision source can also change in response to another control, such as a decision grid. When the pivot state of the decision source changes, the decision pivot updates the layout of the dimension buttons and the selection in the summary combo box.


TDecisionPivot::GroupLayout

TDecisionPivot	See also

Specifies how the dimension buttons and summary control are arranged on the decision pivot.

enum TDecisionButtonPosition { xtHorizontal, xtVertical, xtLeftTop };

__property TDecisionButtonPosition GroupLayout = {read=FStyle, write=SetStyle, nodefault};

Description

Set Layout to specify the organization of a decision pivot. Layout can have one of the following values:

Value	Meaning

xtHorizontal	The controls in the pivot are lined up side by side.

xtVertical	The controls in the pivot are lined up top to bottom.

xtLeftTop	The controls in the pivot are lined up along the edges of the pivot, with the row dimensions down the left side, the column dimensions along the top, and the summary control in the upper left corner.

When Layout is xtLeftTop, the center of the decision pivot is empty. A decision graph or decision grid can be placed in this empty spot so that the buttons line up with the dimensions they control.

When Layout is xtHorizontal or xtVertical, the summary control appears first, followed by a the row dimensions and then the column dimensions. The Groups property can omit any of these from the layout.


TDecisionPivot::Groups

TDecisionPivot	See also

Specifies which controls appear in a decision pivot.

enum TDecisionPivotOption { xtRows, xtColumns, xtSummaries, xtPages };

typedef Set<TDecisionPivotOption, xtRows, xtPages>  TDecisionPivotOptions;

__property TDecisionPivotOptions Groups = {read=FContents, write=SetContents, nodefault};

Description

Set Groups to limit the types of controls that appear in the decision pivot. This allows greater flexibility over where the controls appear in a form. For example, a form can contain three decision pivots: one containing only row dimension buttons, one containing only column dimension buttons, and one containing only the summary selection combo box. These three pivots can then be arranged anywhere on the form.

Groups is a set containing one or more of the following values:

Value	Meaning

xtRows	The pivot contains row dimension buttons.

xtColumns	The pivot contains column dimension buttons.

xtSummaries	The pivot contains a summary selection combo box.


TDecisionPivot::GroupSpacing

TDecisionPivot	See also

Determines the number of pixels that appear between control groups.

__property int GroupSpacing = {read=FGroupSpacing, write=SetGroupSpacing, nodefault};

Description

Set GroupSpacing to control the spaces that appear between the summary combo box, the group of row dimension buttons, and the group of column dimension buttons. Increase GroupSpacing to make the groups of controls appear more distinct. Decrease GroupSpacing to make the decision pivot look more compact.


TDecisionPivot events

TDecisionPivot	Alphabetically	Legend

Derived from TCustomPanel

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDecisionPivot events

TDecisionPivot	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnResize

OnStartDrag


TDecisionPivot methods

TDecisionPivot	Alphabetically

In TDecisionPivot

~TDecisionPivot

SetBounds

TDecisionPivot

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDecisionPivot methods

TDecisionPivot	By object

~TDecisionPivot

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDecisionPivot

Update

UpdateControlState


TDecisionPivot::TDecisionPivot

TDecisionPivot	See also

Creates and initializes an instance of TDecisionPivot.

__fastcall virtual TDecisionPivot(Classes::TComponent* AOwner);

__fastcall TDecisionPivot(HWND ParentWindow) : Extctrls::TCustomPanel(ParentWindow) { }

Description

Call TDecisionPivot indirectly, using the new keyword, to instantiate a decision pivot at runtime. Decision pivots placed on forms at design time are created automatically.

Pass a single Component as a parameter to provide the decision pivot with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the decision pivot in a non-VCL window. This syntax is used when the decision pivot is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object's constructor, TDecisionPivot initializes the following properties:

•	BorderStyle to bsNone and BorderWidth to 3.

•	ButtonAutoSize to true.

•	ButtonHeight to 24 and ButtonWidth to 64.

•	ButtonSpacing to 3 and GroupSpacing to 10.

•	Groups to [xtRows, xtColumns, xtSummaries].

•	GroupLayout to xtHorizontal.


TDecisionPivot::~TDecisionPivot

TDecisionPivot	See also

Destroys an instance of TDecsionPivot.

__fastcall virtual ~TDecisionPivot(void);

Description

Do not call ~TDecisionPivot directly in an application. Instead, use the delete keyword.


TDecisionPivot::SetBounds

TDecisionPivot	See also

Resizes the decision pivot.

virtual void __fastcall SetBounds(int Left, int Top, int Height, int Width);

Description

Use SetBounds to change all of the decision pivot’s boundary properties at once. The same effect can be achieved by setting the Left, Top, Width, and Height properties separately. By setting all four properties at once, SetBounds ensures that the control will not repaint between changes. Specify the values for the Left, Top, Width, and Height properties as the value of the Left, Top, Width, and Height parameters, respectively.

SetBounds overrides the parent class’s method to adjust the layout of the buttons in the decision pivot when the size changes.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomPanel


 TDecisionQuery

Hierarchy	Properties	Methods	Events	See also

Unit

mxtables

Description

TDecisionQuery is a specialized query that prepares crosstabulated data for a decision cube.

Use a TDecisionQuery as the dataset of a decision cube to ensure that the data is properly prepared. TDecisionQuery allows the dimensions and summaries to be defined directly on the dataset analyzed in a decision control. It then prepares an SQL query to provide the information from that dataset in a format that can be used by a decision cube.

Decision cubes can use other types of datasets, but the information must be structured in the same way as the output of a TDecisionQuery object.

Note:	In the Decision Query editor that is displayed from the Decision query component, the query is initially handled in ANSI-92 SQL syntax, then translated (if necessary) into the dialect used by the data source of the query.  Use only ANSI standard SQL in the Decision Query editor. Use the dialect of the data source in the SQL property of the Decision Query.


TDecisionQuery properties

TDecisionQuery	Alphabetically	Legend

Derived from TQuery

Constrained

DataSource

Local

ParamCheck

ParamCount

Params

Prepared

RequestLive

RowsAffected

SQL

SQLBinary

StmtHandle

Text

UniDirectional

Derived from TDBDataSet

Database

DatabaseName

DBHandle

DBLocale

DBSession

Provider

SessionName

UpdateMode

Derived from TBDEDataSet

CacheBlobs

CachedUpdates

CanModify

ExpIndex

Filter

Filtered

FilterOptions

Handle

KeySize

Locale

RecNo

RecordCount

RecordSize

UpdateObject

UpdateRecordTypes

UpdatesPending

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

Constraints

DefaultFields

Designer

EOF

FieldCount

FieldDefs

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDecisionQuery properties

TDecisionQuery	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CacheBlobs

CachedUpdates

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Constrained

Constraints

Database

DatabaseName

DataSource

DBHandle

DBLocale

DBSession

DefaultFields

Designer

DesignInfo

EOF

ExpIndex

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Handle

KeySize

Local

Locale

Modified

Name

Owner

ParamCheck

ParamCount

Params

Prepared

Provider

RecNo

RecordCount

RecordSize

RequestLive

RowsAffected

SessionName

SQL

SQLBinary

State

StmtHandle

Tag

Text

UniDirectional

UpdateMode

UpdateObject

UpdateRecordTypes

UpdatesPending

VCLComObject


TDecisionQuery events

TDecisionQuery	Alphabetically	Legend

Derived from TBDEDataSet

OnServerYield

OnUpdateError

OnUpdateRecord

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TDecisionQuery events

TDecisionQuery	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnServerYield

OnUpdateError

OnUpdateRecord


TDecisionQuery methods

TDecisionQuery	Alphabetically

In TDecisionQuery

~TDecisionQuery

TDecisionQuery

Derived from TQuery

ExecSQL

ParamByName

Prepare

UnPrepare

Derived from TDBDataSet

CheckOpen

CloseDatabase

OpenDatabase

Derived from TBDEDataSet

ApplyUpdates

BookmarkValid

Cancel

CancelUpdates

CommitUpdates

CompareBookmarks

ConstraintCallBack

DisableConstraints

EnableConstraints

FetchAll

GetCurrentRecord

GetIndexInfo

Locate

Lookup

RevertRecord

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Post

Prior

Refresh

Resync

SetFields

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDecisionQuery methods

TDecisionQuery	By object

~TDecisionQuery

ActiveBuffer

Append

AppendRecord

ApplyUpdates

Assign

BookmarkValid

Cancel

CancelUpdates

CheckBrowseMode

CheckOpen

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CloseDatabase

CommitUpdates

CompareBookmarks

ConstraintCallBack

ControlsDisabled

CursorPosChanged

DefaultHandler

Delete

DestroyComponents

Destroying

DisableConstraints

DisableControls

Dispatch

Edit

EnableConstraints

EnableControls

ExecSQL

FetchAll

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindLast

FindNext

FindPrior

First

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GotoBookmark

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

Last

Locate

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

OpenDatabase

ParamByName

Post

Prepare

Prior

Refresh

RemoveComponent

Resync

RevertRecord

SafeCallException

SetFields

TDecisionQuery

Translate

UnPrepare

UpdateCursorPos

UpdateRecord

UpdateStatus


TDecisionQuery::TDecisionQuery

TDecisionQuery

Creates a new TDecisionQuery object.

__fastcall virtual TDecisionQuery(Classes::TComponent* AOwner) : Dbtables::TQuery(AOwner) { }

Description

Call TDecisionQuery indirectly, using the new keyword, to create a decision query at runtime. Decision queries added to forms or data modules at design time are created automatically.


TDecisionQuery::~TDecisionQuery

TDecisionQuery

~TDecisionQuery frees the memory associated with the TDecisionQuery object.

__fastcall virtual ~TDecisionQuery(void) { }

Description

Do not call ~TDecisionQuery directly. Instead, use the delete keyword on the object, which causes ~TDecisionQuery to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet

TBDEDataSet

TDBDataSet

TQuery


 TDecisionSource

Hierarchy	Properties	Methods	Events	See also

TDecisionSource links a decision control to a configuration (pivot state) of the data from a decision cube.

Unit

mxdb

Description

Use TDecisionSource to provide a decision grid or decision graph with cross-tabulated data from a decision cube. TDecisionSource represents a particular pivot state of dimensions from the decision cube into row and column dimensions. TDecisionSource also provides methods to drill down the display of a dimension to focus on summaries over a single value, or hide or show dimensions in the pivot state.

All decision controls that share a decision source display the same pivot state. For example, a form could contain a decision grid and a decision graph linked to the same decision source. Pivoting the dimensions of the decision grid would automatically update the image of the graph accordingly. To display two separate projections of the information from a decision cube in a single form, use two separate decision sources.

The pivot state of a decision source can be changed by manipulating a decision grid or by using a decision pivot.


TDecisionSource properties

TDecisionSource	Alphabetically	Legend

In TDecisionSource

ControlType

CurrentSum

DecisionCube

nColDims

nDataCols

nDataRows

nDims

nOpenColDims

nOpenRowDims

nRowDims

nSums

Ready

SparseCols

SparseRows

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDecisionSource properties

TDecisionSource	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlType

CurrentSum

DecisionCube

DesignInfo

Name

nColDims

nDataCols

nDataRows

nDims

nOpenColDims

nOpenRowDims

nRowDims

nSums

Owner

Ready

SparseCols

SparseRows

Tag

VCLComObject


TDecisionSource::ControlType

TDecisionSource	See also

Specifies how the decision source responds to messages from the decision pivot.

enum TDecisionControlType { xtCheck, xtRadio, xtRadioEx };

__property TDecisionControlType ControlType = {read=FControlType, write=FControlType, nodefault};

Description

Use ControlType to specify what combination of row or column dimensions can be open at the same time. ControlType has one of the following values:

Value	Meaning

xtCheck	Pressing dimension buttons opens or closes an individual dimension, changing the number of open dimensions.

xtRadio	Pressing dimension buttons opens or closes the selected dimension and closes all other dimensions in that direction. When ControlType is xtRadio, at most one row dimension and one column dimension may be open at a time.

xtRadionEx	Pressing dimension buttons opens the selected dimension and closes all other dimensions in that direction or closes the selected dimension and opens another dimension in the same direction. When ControlType is xtRadioEx, exactly one row dimension and one column dimension must be open at any time.


TDecisionSource::CurrentSum

TDecisionSource	See also

Indicates the index of the current summary from the set of active summaries maintained by the decision cube.

__property int CurrentSum = {read=GetCurrentSum, nodefault};

Description

Read CurrentSum to determine which of the active summaries is used to provide values to clients of the decision source. CurrentSum returns 0 if the first active summary is the current summary. CurrentSum returns nSums-1 if the last active summary is the current summary.

To change the current summary, use the SetCurrentSummary method. Use the GetSummaryName method to obtain the name of the current summary.

Note:	Do not pivot, subtotal, or drill the information provided by the Decision source unless the CurrentSum property refers to an additive summary.  Additive Summaries are SUM and COUNT.  AVERAGE (unless calculated internally by the Decision Cube), MAX, and MIN are not additive.


TDecisionSource::DecisionCube

TDecisionSource

Specifies the decision cube that provides the crosstabulated data for the decision source.

__property TDecisionCube* DecisionCube = {read=GetDecisionCube, write=SetDecisionCube};

Description

Set DecisionCube to specify where the decision source should fetch its data. The decision cube maintains a multidimensional array of summaries in a cache. The decision source can provide decision controls with any projection of the data in that cache.


TDecisionSource::nColDims

TDecisionSource	See also

Indicates the number of column dimensions in the current pivot state of the decision source.

__property int nColDims = {read=FAllCols, nodefault};

Description

Read nColDims to determine the number of column dimensions the decision source can provide to a decision control. Column dimensions appear on the y axis of a decision graph or listed along the top of a decision grid. nColDims counts both the open and closed column dimensions. To determine the number of column dimensions actually provided to decision controls, use the nOpenColDims property.


TDecisionSource::nDataCols

Indicates the number of columns provided to the data region of a decision grid.

__property int nDataCols = {read=FColMax, nodefault};

Description

Read nDataCols to determine the number of summarized values the decision source provides for a row in a decision grid. Each of the columns counted by nDataCols represents a combination of values or dimension subtotals for each of the open column dimensions.


TDecisionSource::nDataRows

TDecisionSource	See also

Indicates the number of rows provided to the data region of a decision grid.

__property int nDataRows = {read=FRowMax, nodefault};

Description

Read nDataRows to determine the number of summarized values the decision source provides for a column in a decision grid. Each of the rows counted by nDataRows represents a combination of values or dimension subtotals for each of the open row dimensions.


TDecisionSource::nDims

TDecisionSource	See also

Indicates the number of active dimensions in the decision cube.

__property int nDims = {read=GetDims, nodefault};

Description

Read nDims to determine the number of dimensions the decision source can provide to a decision control. The decision source does not necessarily provide decision controls with all the dimensions counted by the nDims property. Some of the dimensions may be closed.

The dimensions available through the decision source are divided into column dimensions and row dimensions. These are counted by the nColDims and nRowDims properties, respectively. nDims is equal to the sum of nColDims and nRowDims.


TDecisionSource::nOpenColDims

TDecisionSource	See also

Indicates the number of column dimensions provided by the decision source.

__property int nOpenColDims = {read=FActiveCols, nodefault};

Description

Read nOpenColDims to determine the number of open column dimensions the decision source provides to a decision control. Column dimensions appear on the y axis of a decision graph or listed along the top of a decision grid. nOpenColDims counts only the open column dimensions that appear in the decision control. To determine the number of column dimensions potentially available in the current pivot state, use the nColDims property.


TDecisionSource::nOpenRowDims

TDecisionSource	See also

Indicates the number of row dimensions provided by the decision source.

__property int nOpenRowDims = {read=FActiveRows, nodefault};

Description

Read nOpenRowDims to determine the number of open row dimensions the decision source provides to a decision control. Row dimensions appear on the x axis of a decision graph or listed along the left side of a decision grid. nOpenRowDims counts only the open row dimensions that appear in the decision control. To determine the number of row dimensions potentially available in the current pivot state, use the nRowDims property.


TDecisionSource::nRowDims

TDecisionSource	See also

Indicates the number of row dimensions in the current pivot state of the decision source.

__property int nRowDims = {read=FAllRows, nodefault};

Description

Read nRowDims to determine the number of row dimensions the decision source can provide to a decision control. Row dimensions appear on the x axis of a decision graph or listed along the left side of a decision grid. nRowDims counts both the open and closed row dimensions. To determine the number of row dimensions actually provided to decision controls, use the nOpenRowDims property.


TDecisionSource::nSums

TDecisionSource	See also

Indicates the number of active summaries in the decision cube.

__property int nSums = {read=GetSums, nodefault};

Description

Read nSums to determine the number of summary types the decision source can provide to a decision control. The decision source can only provide decision controls with a single summary at a time. The CurrentSum property indicates which of the nSums possibilities is currently provided by the decision source.


TDecisionSource::Ready

TDecisionSource	See also

Indicates whether the decision source is linked to an active decision cube.

__property bool Ready = {read=GetReady, nodefault};

Description

Read Ready to determine whether the decision source can provide data to a decision control.


TDecisionSource::SparseCols

TDecisionSource	See also

Indicates whether empty columns are removed from the current projection.

__property bool SparseCols = {read=GetColSparsing, write=SetColSparsing, nodefault};

Description

Set SparseCols to true to display columns that are empty in the current pivot state. Set SparseCols to false to show only those dimension values that have summarized data over one or more of the row dimensions.

Note:	SparseCols doesn’t change the value returned by GetDimensionMemberCount.


TDecisionSource::SparseRows

TDecisionSource	See also

Indicates whether empty rows are removed from the current projection.

__property bool SparseRows = {read=GetRowSparsing, write=SetRowSparsing, nodefault};

Description

Set SparseRows to true to display rows that are empty in the current pivot state. Set SparseRows to false to show only those dimension values that have summarized data over one or more of the column dimensions.

Note:	SparseRows doesn’t change the value returned by GetDimensionMemberCount.


TDecisionSource events

TDecisionSource	Alphabetically	Legend

In TDecisionSource

OnAfterPivot

OnBeforePivot

OnLayoutChange

OnNewDimensions

OnStateChange

OnSummaryChange


TDecisionSource events

TDecisionSource	By object	Legend

OnAfterPivot

OnBeforePivot

OnLayoutChange

OnNewDimensions

OnStateChange

OnSummaryChange


TDecisionSource::OnAfterPivot

TDecisionSource	See also

Occurs immediately after the current pivot state changes.

__property Classes::TNotifyEvent OnAfterPivot = {read=FOnAfterPivot, write=FOnAfterPivot};

Description

Write an OnAfterPivot event handler to take specific action after the information provided by the decision source changes but before any decision controls are updated to reflect the change. This is a good opportunity to save information about the pivot state.

When the pivot state of the decision source changes, an OnBeforePivot occurs when the results of the change have been calculated, and OnAfterPivot occurs when the decision source has been updated to reflect the change. Once the decision controls that are linked to the decision pivot are updated to reflect the change, an OnLayoutChange event occurs.


TDecisionSource::OnBeforePivot

TDecisionSource	See also

Occurs just before the current pivot state changes.

__property Classes::TNotifyEvent OnBeforePivot = {read=FOnBeforePivot, write=FOnBeforePivot};

Description

Write an OnBeforePivot event handler to take specific action just before the information provided by the decision source changes. When OnBeforePivot occurs, the results of the pivot have been computed but not implemented. Use the GetGroup, GetIndex, GetState, GetValue, and GetRowState methods to get information about the pivot state that is about to be implemented. To get information about the pivot state that is ending, save the dimension information in an OnAfterPivot event handler. The information about the new state can then be compared to information captured the last time the pivot state was changed. The OnBeforePivot event handler can make additional alterations to the pivot state using the methods of the decision source.


TDecisionSource::OnLayoutChange

TDecisionSource	See also

Occurs immediately after decision controls are updated to reflect a change to the pivot state of the decision source.

__property Classes::TNotifyEvent OnLayoutChange = {read=FOnLayoutChange, write=FOnLayoutChange};

Description

Write an OnLayoutChange event handler to respond to changes in the configuration of the active dimensions. OnLayoutChange occurs when the pivot or drill state changes, but the information cached by the decision cube remains the same. When OnLayoutChange occurs, the information the decision source can potentially provide does not change, only the current configuration of that information. To respond to changes in the data cached by the decision cube, use the OnNewDimensions event.


TDecisionSource::OnNewDimensions

TDecisionSource	See also

Occurs immediately after the data provided by the decision cube changes.

__property Classes::TNotifyEvent OnNewDimensions = {read=FOnNewDimensions, write=FOnNewDimensions};

Description

Write an OnNewDimensions event handler to respond to changes that alter the data array, such as when the active property of a dimension in the data cube changes. When OnNewDimensions occurs, the information the decision source can provide changes. To respond to changes that reorganize the data but do not change the data cached by the data cube, use the OnEndPivot or OnLayoutChange event. To respond to changes in the data cube itself, use the OnStateChange event.


TDecisionSource::OnStateChange

TDecisionSource	See also

Occurs when the DecisionCube property changes.

__property Classes::TNotifyEvent OnStateChange = {read=FOnStateChange, write=FOnStateChange};

Description

Write an OnStateChange event handler to respond when the DecisionCube property changes or when the decision cube’s Active property changes. To respond to less drastic changes, use the OnNewDimensions event, the OnLayoutChange event, or the OnEndPivot event.


TDecisionSource::OnSummaryChange

TDecisionSource	See also

Occurs immediately after the CurrentSum property changes.

__property Classes::TNotifyEvent OnSummaryChange = {read=FonSummaryChange, write=FonSummaryChange};

Description

Write an OnSummaryChange event handler to take specific action when the summary provided by the decision source changes. The value of the CurrentSum property reflects the new current summary.


TDecisionSource methods

TDecisionSource	Alphabetically

In TDecisionSource

~TDecisionSource

CloseDimIndexRight

DrillDimIndex

Get2DDataAsVariant

GetActiveDim

GetDataAsString

GetDataAsVariant

GetDimensionMemberCount

GetDimensionName

GetGroup

GetGroupExtent

GetIndex

GetMemberAsString

GetMemberAsVariant

GetRowState

GetState

GetSummaryName

GetValue

GetValueArray

GetValueIndex

MoveDimIndexes

OpenDimIndexLeft

OpenDimIndexRight

SetCurrentSummary

SwapDimIndexes

TDecisionSource

ToggleDimIndex

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDecisionSource methods

TDecisionSource	By object

~TDecisionSource

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CloseDimIndexRight

DefaultHandler

DestroyComponents

Destroying

Dispatch

DrillDimIndex

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

Get2DDataAsVariant

GetActiveDim

GetDataAsString

GetDataAsVariant

GetDimensionMemberCount

GetDimensionName

GetGroup

GetGroupExtent

GetIndex

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMemberAsString

GetMemberAsVariant

GetNamePath

GetParentComponent

GetRowState

GetState

GetSummaryName

GetValue

GetValueArray

GetValueIndex

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

MoveDimIndexes

NewInstance

OpenDimIndexLeft

OpenDimIndexRight

RemoveComponent

SafeCallException

SetCurrentSummary

SwapDimIndexes

TDecisionSource

ToggleDimIndex


TDecisionSource::CloseDimIndexRight

TDecisionSource	See also

Closes a dimension.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall CloseDimIndexRight(TDimGroup dimGroup, int Index, bool bOpen);

Description

Call CloseDimIndexRight to close a dimension so that it does not appear in the projection displayed by decision controls that use the decision source.

CloseDimIndexRight closes the first open dimension after the dimension identified by the Index parameter. If the dimGroup parameter is dgRow, Index identifies a row dimension, where 0 specifies the first row dimension, 1 specifies the second row dimension, and so on. If the dimGroup parameter is dgCol, Index identifies a column dimension, starting with an index of 0 for the first column dimension. No other values for dimGrouop should be used with the CloseDimIndexRight method. To close the first open row or column dimension, set Index to -1. The bOpen parameter specifies whether closed dimensions are counted when interpreting Index. Only open dimensions are counted when bOpen is true.


TDecisionSource::TDecisionSource

TDecisionSource	See also

Creates and initializes an instance of TDecisionSource.

__fastcall virtual TDecisionSource(Classes::TComponent* AOwner);

Description

Call TDecisionSource indirectly, using the new keyword, to instantiate a decision source at runtime. Decision source objects placed in forms or data modules at design time are created automatically.


TDecisionSource::~TDecisionSource

TDecisionSource	See also

Destroys an instance of TDecisionSource.

__fastcall virtual ~TDecisionSource(void);

Description

Do not call ~TDecisionSource directly in an application. Instead, use the delete keyword.

For all decision controls linked to the decision source, ~TDecisionSource changes the DecisionSource property to NULL.


TDecisionSource::DrillDimIndex

TDecisionSource	See also

Collapses a dimension to focus on a single value.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall DrillDimIndex(TDimGroup dimGroup, int Index, int ValueIndex, bool bOpen);

Description

Call DrillDimIndex to “drill down” on a dimension, so that only the summaries for a single value are displayed.

The dimGroup parameter specifies the type of dimension to be drilled. If dimGroup is dgRow, the Index parameter identifies a row dimension to be drilled. If dimGroup is dgCol, Index identifies a column dimension to be drilled. No other values for dimGroup should be used with the DrillDimIndex method. The first row or column dimension has an Index of 0, the second dimension has an Index of 1, and so on. The ValueIndex parameter is the index of single value from all values over the dimension that should be displayed. To display only the summaries over the entire dimension, rather than for a single value along the dimension, set ValueIndex to -1. The bOpen parameter specifies whether closed dimensions are counted when interpreting Index. Only open dimensions are counted when bOpen is true.

To restore the dimension from its drilled state so that it displays all values again, use the ToggleDimIndex method.

Note:	Do not drill a dimension of the Decision Source unless the CurrentSum property specifies an additive summary. Additive Summaries are SUM and COUNT.  AVERAGE (unless calculated internally by the Decision Cube), MAX, and MIN are not additive.


TDecisionSource::Get2DDataAsVariant

TDecisionSource	See also

Returns the summary for a two dimensional projection of the current pivot state.

System::Variant __fastcall Get2DDataAsVariant(int iDimA, int iDimB, int aValueIndex, int bValueIndex);

Description

Call Get2DDataAsVariant to obtain the summary value from the decision cube that corresponds to the coordinates of aValueIndex on the iDimA dimension and bValueIndex on the iDimB dimension. The returned value is a variant that summarizes all values over the other active dimensions, unless they are drilled. For drilled dimensions, only the drilled value is included in the summary.

The iDimA and iDimB parameters specify the dimensions for the two dimensional projection, where 0 indicates the first active dimension, 1 indicates the second active dimension, and so on. The dimension indexes are expressed as absolute indexes. To obtain an absolute index from a row or column index, use the GetActiveDim method. The aValueIndex and bValueIndex parameters are the indexes of the values on the two dimensions, where 0 indicates the first value, 1 indicates the second value, and so on. Use the GetMemberAsString or GetMemberAsVariant method to obtain the field values that correspond to the aValueIndex and bValueIndex parameters.


TDecisionSource::GetActiveDim

TDecisionSource	See also

Converts a row-specific or column-specific dimension index into an absolute dimension index.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

int __fastcall GetActiveDim(TDimGroup dimGroup, int index, bool bOpen);

Description

Call GetActiveDim to obtain the index of a dimension in the decision cube from its position in a decision grid. The names and values of row dimensions appear in the label cells on the right of the decision grid. The first row dimension appears in the first column, the second row dimension appears in the second column, and so on. Similarly, column dimensions appear in the label cells on the top of the decision grid, with the first column dimension appearing in the first row of the grid.

The dimGroup parameter indicates whether the dimension of interest is a row dimension or column dimension. If dimGroup is dgRow, the dimension is a row dimension. If dimGroup is dgCol, the dimension is a column dimension. GetActiveDim is not implemented for other values of dimGroup. The Index parameter indicates the position of the dimension in the set of row or column dimensions, where 0 specifies the first row or column dimension, 1 specifies the second dimension, and so on. The bOpen parameter specifies whether closed dimensions are counted when interpreting Index. Only open dimensions are counted when bOpen is true.

GetActiveDim returns the absolute index of the dimension. Absolute indexes are used by many methods of the decision source, such as GetDimensionName or GetMemberAsString.

Note:	To obtain a row-specific index or column-specific index from an absolute dimension index, use the GetIndex method.


TDecisionSource::GetDataAsString

TDecisionSource	See also

Returns the data value that should appear in the cell of a decision grid, formatted as a string.

System::AnsiString __fastcall GetDataAsString(int ARow, int ACol, int &SubLevel);

Description

Call GetDataAsString to obtain the display string for a data cell in a decision grid. The ARow and ACol parameters indicate the row and column numbers of the cell in the decision grid, where (0,0) specifies the top left cell in the data region.

GetDataAsString computes the dimension coordinates in the decision cube that correspond to the row and column indexes, making note of all dimensions over which subtotals must be taken. It then obtains the summary value from the decision cube, combining values for each summarized dimension. GetDataAsString returns the final summary value, formatted as a string. It also returns the number of summarized dimensions in the SubLevel parameter.


TDecisionSource::GetDataAsVariant

TDecisionSource	See also

Returns the data value that should appear in the cell of a decision grid.

System::Variant __fastcall GetDataAsVariant(int Arow, int ACol, int &SubLevel);

Description

Call GetDataAsVariant to obtain the value of a data cell in a decision grid. The ARow and ACol parameters indicate the row and column numbers of the cell in the decision grid, where (0,0) specifies the top left cell in the data region.

GetDataAsVariant computes the dimension coordinates in the decision cube that correspond to the row and column indexes, making note of all dimensions over which subtotals must be taken. It then obtains the summary value from the decision cube, combining values for each summarized dimension. GetDataAsVariant returns the final summary value. It also returns the number of summarized dimensions in the SubLevel parameter.


TDecisionSource::GetDimensionMemberCount

TDecisionSource	See also

Returns the number of distinct values to be displayed for a given dimension.

int __fastcall GetDimensionMemberCount(int iDim);

Description

Call GetDimensionMemberCount to determine the number of values in the dimension identified by the iDim parameter. The iDim parameter is the absolute index of the dimension, where 0 indicates the first active dimension in the decision cube, 1 indicates the second active dimension, and so on. To convert from a row-specific or column-specific dimension index into an absolute dimension index, use the GetActiveDim method.

GetDimensionMemberCount provides an upper limit to the ValueIndex parameter of the GetMemberAsString or GetMemberAsVariant method.

Note:	The value returned by GetDimensionMemberCount may change depending on the pivot state.


TDecisionSource::GetDimensionName

TDecisionSource	See also

Returns the display name for a dimension.

System::AnsiString __fastcall GetDimensionName(int iDim);

Description

Call GetDimensionName to obtain a name to display as a label for the dimension. The iDim parameter is the absolute index of the dimension, where 0 indicates the first active dimension in the decision cube, 1 indicates the second active dimension, and so on. To convert from a row-specific or column-specific dimension index into an absolute dimension index, use the GetActiveDim method.

The name of a dimension is often the name of the field the dimension represents. The dimension name can be changed in the Decision Cube Editor or by setting the Name property of the dimension in the dimension map of the decision cube.


TDecisionSource::GetGroup

TDecisionSource	See also

Indicates where a dimension appears in the current pivot state.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

TDimGroup __fastcall GetGroup(int iDim);

Description

Call GetGroup to determine how the dimension specified by the iDim parameter is used in the current pivot state. The iDim parameter is the absolute index of the dimension, where 0 is the first active dimension, 1 is the second active dimension, and so on.

If the dimension is a row dimension (displayed to the left of a decision grid or on the y-axis of a decision graph), GetGroup returns dgRow. If it is a column dimension (displayed at the top of a decision grid or on the x-axis of a decision graph), GetGroup returns dgCol. If the dimension is a paged dimension (not appearing in the decision control but limiting the data to a single value along the dimension), GetGroup returns dgPage. GetGroup never returns dgSum or dgNone.

Note:	To determine the position of the dimension within the row dimensions or column dimensions, use the GetIndex method.


TDecisionSource::GetGroupExtent

TDecisionSource	See also

Returns the range of cell indexes for a single value of a dimension.

struct TDimRange

{

  int First;

  int Last;

};

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

TDimRange __fastcall GetGroupExtent(TDimGroup dimGroup, int Index, int Cell);

Description

Call GetGroupExtent to find the range of cells in a decision grid that have the same value on a given dimension as the cell specified by the Cell parameter. Cell is the index of the row or column containing the cell, where 0 specifies the first row or column in the data area of a decision grid. If dimGroup is dgRow, Cell identifies a row of the grid. If dimGroup is dgCol, Cell identifies a column of the grid. Do not use other values for dimGroup. Index specifies the row-specific or column-specific index of the dimension.

For example, if a decision grid has two row dimensions listed in the first two columns of the decision grid, the line

MyRange = DecisionSource1->GetGroupExtent(dgRow, 0, 3);

sets MyRange to the range of row indexes for cells that have the same value on the first row dimension as the third cell. The number of cells in this range is the same as the value returned by GetDimensionMemberCount for the second open row dimension. The line

MyRange = DecisionSource1->GetGroupExtent(dgRow, 1, 3);

sets MyRange to the range from 3 to 3, because the second row dimension is the innermost row dimension, so each value is represented by a single row.

Note:	If the dimension includes subtotals, the subtotal cell is included in the range returned by GetGroupExtent.


TDecisionSource::GetIndex

TDecisionSource	See also

Returns the row-specific or column-specific index of a dimension.

int __fastcall GetIndex(int iDim, bool bOpen);

Description

Call GetIndex to obtain the row-specific index or column-specific index of a dimension from its index in the decision cube. GetIndex returns 0 for the first row dimension or the first column dimension. GetIndex returns 1 for the second row dimension or the second column dimension, and so on. The iDim parameter is the absolute index of the dimension. If the bOpen parameter is true, GetIndex is the position of the dimension when only open dimensions are counted. If bOpen is false, all dimensions, including closed dimensions are counted.

Use the GetGroup method to determine whether the index returned by GetIndex is a row-specific index (GetGroup returns dgRow) or a column-specific index (GetGroup returns dgCol).

To obtain the index of a dimension in the decision cube from its row-specific or column-specific index, use the GetActiveDim method.


TDecisionSource::GetMemberAsString

TDecisionSource	See also

Returns the label string for a dimension value.

System::AnsiString __fastcall GetMemberAsString(int iDim, int ValueIndex);

Description

Call GetMemberAsString to obtain the value indicated by the ValueIndex parameter along the dimension specified by the iDim parameter, formatted as a string.

The iDim parameter is the absolute index of the dimension, where 0 indicates the first active dimension in the decision cube, 1 indicates the second active dimension, and so on. To convert from a row-specific or column-specific dimension index into an absolute dimension index, use the GetActiveDim method.

The ValueIndex parameter is the index of a value along the dimension, where 0 specifies the first value of the dimension and GetDimensionMemberCount returns the number of values along the dimension.


TDecisionSource::GetMemberAsVariant

TDecisionSource	See also

Returns a value along a dimension.

System::Variant __fastcall GetMemberAsVariant(int iDim, int ValueIndex);

Description

Call GetMemberAsVariant to obtain the value indicated by the ValueIndex parameter along the dimension specified by the iDim parameter.

The iDim parameter is the absolute index of the dimension, where 0 indicates the first active dimension in the decision cube, 1 indicates the second active dimension, and so on. To convert from a row-specific or column-specific dimension index into an absolute dimension index, use the GetActiveDim method.

The ValueIndex parameter is the index of a value along the dimension, where 0 specifies the first value of the dimension and GetDimensionMemberCount returns the number of values along the dimension.


TDecisionSource::GetRowState

TDecisionSource	See also

Indicates whether the adjacent dimensions are open or closed.

enum TRowStates { rcNextOpen, rcPrevOpen, rcNextClosed, rcPrevClosed };

typedef Set<TRowStates, rcNextOpen, rcPrevClosed> TRowState;

TRowState __fastcall GetRowState(int iDim);

Description

Call GetRowState to determine the state of the dimensions that are adjacent to a dimension in the current pivot state. The iDim parameter specifies the absolute index of the dimension whose neighbors are to be checked. When iDim is 0, the dimension is the first active dimension in the decision cube. When iDim is 1, it is the second active dimension, and so on.

The return value includes rcPrevOpen if the previous dimension is open or rcPrevClosed if the previous dimension is closed. The return value includes rcNextOpen if the following dimension is open or rcNextClosed if it is closed. The first row or column dimension does not include either rcPrevOpen or rcPrevClosed. The last row or column does not include either rcNextOpen or rcNextClosed.

Note:	Do not be confused by the name of the GetRowState method. It provides information about the adjacent column dimensions if iDim specifies a column dimension, or information about the adjacent row dimensions if iDim specifies a row dimension.


TDecisionSource::GetState

TDecisionSource	See also

Returns the state of a dimension.

enum TDimState { dmClosed, dmOpen, dmDrilled, dmPaged, dmNone };

TDimState __fastcall GetState(int iDim);

Description

Call GetState to determine whether a specified dimension is open, closed, or drilled. The iDim parameter is the absolute index of the dimension, where 0 specifies the first active dimension in the decision cube, 1 specifies the second active dimension, and so on. GetState returns one of the following values:

Value	Meaning

dmClosed	The dimension is closed. None of its values appear in the decision control.

dmOpen	The dimension is open. All of its values appear in the decision control.

dmDrilled	The dimension is drilled. Only a single value (or a summary over all values) along the dimension appears in the decision control.

dmPaged	The dimension can only display a single value or summarize all values together.

dmNone	The dimension is not active.

Note:	The state dmDrilled appears the same as dmPaged in a decision control. However, drilled dimensions can be changed to open or closed, while paged dimensions can’t change their state. Paged dimensions use considerably less memory than other types.


TDecisionSource::GetSummaryName

TDecisionSource	See also

Returns the name of an active summary in the decision cube.

System::AnsiString __fastcall GetSummaryName(int iSum);

Description

Call GetSummaryName to determine the name of a summary. The iSum parameter is the index of the summary from the list of active summaries available from the decision cube. Use GetSummaryName to determine the name of the possible summaries that can be set using the SetCurrentSummary method.


TDecisionSource::GetValue

TDecisionSource	See also

Returns the drill value of a drilled or paged dimension.

int __fastcall GetValue(int iDim);

Description

Call GetValue to determine the value focused on by a drilled or paged dimension. Drilled dimensions and paged dimensions display only the data for a single field value along the dimension. GetValue returns the index of that single value. The value itself can be obtained from this index by calling the GetMemberAsString or GetMemberAsVariant method.

The iDim parameter is the absolute index of the drilled or paged dimension, where 0 specifies the first active dimension in the decision cube, 1 specifies the second active dimension, and so on.

Note:	If the dimension is drilled so that it displays only summaries over all the values in the dimension, GetValue returns -1. If the dimension specified by the iDim parameter is not drilled or paged, GetValue returns -1.


TDecisionSource::GetValueArray

TDecisionSource	See also

Returns the values of all dimension fields over which a data cell is summarized.

bool __fastcall GetValueArray(int ACol, int ARow, Mxarrays::TSmallIntArray* &ValueArray);

Description

Call GetValueArray to obtain the coordinates of a data cell from a decision grid in the multidimensional array maintained by the decision cube. The ACol and ARow parameters represent the indexes of the column and row containing the cell, where (0,0) specifies the upper left data cell, not the top left cell in the grid. The ValueArray parameter returns the indexes of the field values along each active dimension. An index of -1 indicates that the cell represents a subtotal across all values in the corresponding dimension. Use the GetMemberAsString or GetMemberAsVariant method to convert the indexes in the ValueArray parameter into field values. GetValueArray returns a boolean indicating whether the function was successful.


TDecisionSource::GetValueIndex

TDecisionSource	See also

Returns the index of a single dimension value that corresponds to a cell in a decision grid.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

int __fastcall GetValueIndex(TDimGroup dimGroup, int Index, int Cell, bool &isBreak, bool &isSum);

Description

Call GetValueIndex to obtain the coordinate of a cell in a decision grid along the dimension specified by the Index parameter. The dimGroup parameter indicates whether the dimension is a row dimension (dgRow) or a column dimension (dgCol). Do not call GetValueIndex with dimGroup set to a dimension group other than dgRow or dgCol. The Index parameter is the row-specific or column-specific index of the dimension. The first row or column dimension has an Index of 0, the second dimension has an Index of 1, and so on. The Cell parameter is the index of the cell row or column, where 0 specifies the first row or column in the data region of the grid.

In addition to returning the index of the dimension value, GetValueIndex provides additional information about the position of Cell within the cells for the dimension. GetValueIndex sets isBreak to true when Cell is the first cell in the dimension group with the returned value on the specified dimension. GetValueIndex sets iSum to true when Cell represents a subtotal over the dimension.


TDecisionSource::MoveDimIndexes

TDecisionSource	See also

Changes the position of a dimension.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall MoveDimIndexes(TDimGroup SdimGroup, TDimGroup DdimGroup, int SIndex, int DIndex, bool bOpen);

Description

Call MoveDimIndexes to change the pivot state of the decision grid. MoveDimIndexes moves the dimension indicated by the SIndex and SDimGroup parameters to the position indicated by the DIndex and DDimGroup parameters.

The SDimGroup and DDimGroup parameters specify whether the dimension position is along the rows of a decision grid (SDimGroup or DDimGroup is dgRow), or across the columns of the decision grid (SDimGroup or DDimGroup is dgCol). The SIndex and DIndex parameters indicate the index of the dimension position among the row dimensions or column dimensions, where 0 specifies the first position, 1 specifies the second position, and so on. The bOpen parameter specifies whether closed dimensions are counted when interpreting the SIndex and DIndex parameters. When bOpen is true, only open dimensions are counted.

Note:	Do not move a dimension of the Decision Source unless the CurrentSum property specifies an additive summary. Additive Summaries are SUM and COUNT.  AVERAGE (unless calculated internally by the Decision Cube), MAX, and MIN are not additive.


TDecisionSource::OpenDimIndexLeft

TDecisionSource	See also

Opens the first closed dimension that appears before a specified dimension.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall OpenDimIndexLeft(TDimGroup dimGroup, int Index, bool bOpen);

Description

Call OpenDimIndexLeft to reopen a closed dimension so that its values appear in the decision control.

OpenDimIndexLeft opens the first closed dimension before the dimension identified by the Index parameter. If the dimGroup parameter is dgRow, Index identifies a row dimension, where 0 specifies the first row dimension, 1 specifies the second row dimension, and so on. If the dimGroup parameter is dgCol, Index identifies a column dimension, starting with an index of 0 for the first column dimension. No other values for dimGrouop should be used with the OpenDimIndexLeft method. To open the last closed row or column dimension, set Index to -1. The bOpen parameter specifies whether closed dimensions are counted when interpreting Index. Only open dimensions are counted when bOpen is true.


TDecisionSource::OpenDimIndexRight

TDecisionSource	See also

Opens the first closed dimension that appears after a specified dimension.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall OpenDimIndexRight(TDimGroup dimGroup, int Index, bool bOpen);

Description

Call OpenDimIndexRight to reopen a closed dimension so that its values appear in the decision control.

OpenDimIndexRight opens the first closed dimension after the dimension identified by the Index parameter. If the dimGroup parameter is dgRow, Index identifies a row dimension, where 0 specifies the first row dimension, 1 specifies the second row dimension, and so on. If the dimGroup parameter is dgCol, Index identifies a column dimension, starting with an index of 0 for the first column dimension. No other values for dimGrouop should be used with the OpenDimIndexRight method. To open the first closed row or column dimension, set Index to -1. The bOpen parameter specifies whether closed dimensions are counted when interpreting Index. Only open dimensions are counted when bOpen is true.


TDecisionSource::SetCurrentSummary

TDecisionSource	See also

Specifies which summary is provided by the decision source.

void __fastcall SetCurrentSummary(int Value);

Description

The decision cube maintains a set of active summaries in its cache. The decision source can only present one of those summaries to decision controls. Call SetCurrentSummary to specify which of the active summaries is surfaced by the decision source. The Value parameter specifies the index of the summary in the list of active summaries maintained by the decision cube.

To obtain the names of the active summaries from which the current summary is chosen, use the GetSummaryName method.


TDecisionSource::SwapDimIndexes

TDecisionSource	See also

Interchanges the positions of two dimensions.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall SwapDimIndexes(TDimGroup SdimGroup, TDimGroup DdimGroup, int SIndex, int DIndex, bool bOpen);

Description

Call SwapDimIndexes to change the pivot state of the decision grid. SwapDimIndexes interchanges the positions of the dimension indicated by the SIndex and SDimGroup parameters and the dimension indicated by the DIndex and DDimGroup parameters.

The SDimGroup and DDimGroup parameters specify whether the dimension position is along the rows of a decision grid (SDimGroup or DDimGroup is dgRow), or across the columns of the decision grid (SDimGroup or DDimGroup is false). The SIndex and DIndex parameters indicate the index of the dimension position among the row dimensions or column dimensions, where 0 specifies the first position, 1 specifies the second position, and so on. The bOpen parameter specifies whether closed dimensions are considered when interpreting the SIndex and DIndex parameters. When bOpen is true, only open dimensions are counted.

Note:	Do not move a dimension of the Decision Source unless the CurrentSum property specifies an additive summary. Additive Summaries are SUM and COUNT.  AVERAGE (unless calculated internally by the Decision Cube), MAX, and MIN are not additive.


TDecisionSource::ToggleDimIndex

TDecisionSource	See also

Changes whether a dimension is open, closed, or drilled.

enum TDimGroup { dgRow, dgCol, dgSum, dgPage, dgNone };

void __fastcall ToggleDimIndex(TDimGroup dimGroup, int Index, bool bOpen);

Description

Call ToggleDimIndex to open a closed dimension, close an open dimension, or expand a drilled dimension.

When dimGroup is dgRow, the Index parameter specifies the row-specific index of the dimension. When dimGroup is dgCol, Index specifies the column-specific index of the dimension. The first row or column dimension has an Index of 0, the second dimension has an Index of 1, and so on. The bOpen parameter specifies whether closed dimensions should be counted when interpreting the Index parameter. When bOpen is true, only open dimensions are counted.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


TDefCollection

Hierarchy	Properties	Methods	See also

TDefCollection holds the definition objects (TNamedItem) that represent the specifications for database entities such as fields or indexes.

Unit

db

Description

TDefCollection is used as a base class for collections of definition objects such as index or field definitions.  These definition objects are used by a dataset to specify the attributes of a database entity that will be created by the dataset.

Use the properties and methods of TDefCollection to:

Access a specific definition object.

Add or delete definition objects from the list.

Find out how many definition objects are defined.

Copy a set of definitions to another dataset.


TDefCollection properties

TDefCollection	Alphabetically	Legend

In TDefCollection

Dataset

Updated

Derived from TCollection

Count

ItemClass

Items


TDefCollection properties

TDefCollection	By object	Legend

Count

Dataset

ItemClass

Items

Updated


TDefCollection::Dataset

TDefCollection	See also

Indicates the dataset that uses the TDefCollection object to manage its definition objects.

__property TDataSet* Dataset = {read=FDataset};

Description

Use Dataset to access the dataset that will create the objects specified by the definitions in the Items array.


TDefCollection::Updated

TDefCollection	See also

Indicates whether the definition objects in the Items array match the corresponding instantiated objects in the dataset.

__property bool Updated = {read=FUpdated, write=FUpdated, nodefault};

Description

Use Updated to determine whether the definitions managed by the TDefCollection object match the corresponding entities (fields or indexes) of the dataset.  Updated is set to true when the definitions are retrieved from the dataset at design time, or when the definitions are used to create the corresponding entities in the dataset.  Updated is set to false when the properties of the definition objects are changed.


TDefCollection methods

TDefCollection	Alphabetically

In TDefCollection

~TDefCollection

Find

IndexOf

TDefCollection

Derived from TCollection

Add

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDefCollection methods

TDefCollection	By object

~TDefCollection

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

Find

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

IndexOf

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDefCollection


TDefCollection::TDefCollection

TDefCollection	See also

Instantiates a TDefCollection object.

__fastcall TDefCollection(TDataSet* ADataset, System::TMetaClass* AClass);

Description

Do not call the TDefCollection method.  TDefCollection objects are created by the dataset that uses them to manage definition objects.  The ADataset parameter specifies the dataset that creates the TDefCollection object.  It becomes the value of the Dataset property.  The AClass parameter specifies a descendant class of TNamedItem, and indicates the type of definition objects in the Items property array.


TDefCollection::Find

TDefCollection	See also

Locates a definition object in the Items array from its name.

TNamedItem* __fastcall Find(const System::AnsiString AName);

Description

Call Find to obtain information about a particular definition object. Specify the name of the definition object as the value of the Name parameter.


TDefCollection::IndexOf

TDefCollection	See also

Finds the index number of a definition in the Items array from its name.

int __fastcall IndexOf(const System::AnsiString AName);

Description

Use the IndexOf method to locate the position of a definition in the Items property array. IndexOf returns a value from zero (the first position) to Count - 1. Specify the name of the definition as the Name parameter.

If Items contains no definition with the specified Name, the return value is -1.


TDefCollection::~TDefCollection

TDefCollection

~TDefCollection frees the memory associated with the TDefCollection object.

__fastcall virtual ~TDefCollection(void) { }

Description

Do not call ~TDefCollection directly. Instead, use the delete keyword on the object, which causes ~TDefCollection to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


TDesigner

Hierarchy	Properties	Methods

TDesigner provides the basis for all form designers in the C++Builder environment.

Unit

forms

Description

The abstract designer object is the base class for all objects that represent a designer such as the form designer in the IDE. It provides two properties used by all designer objects and defines five pure virtual methods that working designer objects must override.


TDesigner properties

TDesigner	Alphabetically

In TDesigner

Form

IsControl


TDesigner properties

TDesigner	By object

Form

IsControl


TDesigner::Form

TDesigner

Provides a reference to the form currently being designed.

__property TCustomForm* Form = {read=FCustomForm, write=FCustomForm};

Description

Use Form to access the form, if any, that is being designed. When the user specifies changes in the form designer, the changes can be made to the form specified by the Form property.

Note:	Not every designer has a form.  For example, when the designer is used for a data module, remote data module, or active form, the Form property should not be used.


TDesigner::IsControl

TDesigner

Specifies whether the form is in its form state or its control state.

__property bool IsControl = {read=GetIsControl, write=SetIsControl, nodefault};

Description

If the designer is used to create a control, rather than a form, set IsControl to true when the user finishes designing the control.


TDesigner methods

TDesigner	Alphabetically

In TDesigner

~TDesigner

IsDesignMsg

Modified

Notification

PaintGrid

TDesigner

ValidateRename

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDesigner methods

TDesigner	By object

~TDesigner

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

IsDesignMsg

MethodAddress

MethodName

Modified

NewInstance

Notification

PaintGrid

SafeCallException

TDesigner

ValidateRename


TDesigner::IsDesignMsg

TDesigner

Determines when a message should be handled by a designer.

virtual bool __fastcall IsDesignMsg(Controls::TControl* Sender, Messages::TMessage &Message) = 0;

Description

IsDesignMsg is called for each message sent to a component in the designer. This method returns true if the message is a design message, meaning one the designer should handle for the component.


TDesigner::Modified

TDesigner

Notifies property and component editors when a change is made to a component.

virtual void __fastcall Modified(void) = 0;

Description

When any change is made to a component, the property and component editors call this method, allowing the designer to respond to the change.


TDesigner::Notification

TDesigner

Allows the designer to respond when a notification is sent to the form.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation) = 0;

Description

When a form receives a notification, it calls the Notification method of the designer, allowing the designer to respond to all the notifications the form receives.


TDesigner::PaintGrid

TDesigner

Paints the alignment grid on the form's canvas.

virtual void __fastcall PaintGrid(void) = 0;

Description

Forms that are associated with a designer call PaintGrid in response to Windows paint messages. If there is no designer associated with the form, the form’s Paint method is called instead.


TDesigner::ValidateRename

TDesigner 	See also

Provides the interface for a method to restrict the names that can be given to components on the form that is being designed.

virtual void __fastcall ValidateRename(Classes::TComponent* AComponent, const System::AnsiString CurName, const System::AnsiString NewName) = 0;

Description

This method is usually called by the form's ValidateRename method to provide tighter restrictions on renaming, such as prohibiting reserved words.


TDesigner::TDesigner

TDesigner

Creates a new TDesigner object.

__fastcall TDesigner(void) : System::TObject() { }

Description

Do not create instances of TDesigner. IDE creates an appropriate descendant of TDesigner when an object such as a form or data module is created at design time.


TDesigner::~TDesigner

TDesigner

~TDesigner frees the memory associated with the TDesigner object.

__fastcall virtual ~TDesigner(void) { }

Description

Do not destroy instances of TDesigner. The IDE destroys designers when they are no longer needed.


Hierarchy

TObject


EDimIndexError

Hierarchy	Properties	Methods	See also

EDimIndexError is the exception class for when an invalid index is used to specify a dimension in a decision source.

Unit

mxdb

Description

EDimIndexError is thrown when any of the methods of a decision source are called with a dimension index that does not correspond to a dimension.


EDimIndexError properties

EDimIndexError	Alphabetically

Derived from Exception

HelpContext

Message


EDimIndexError properties

EDimIndexError	By object

HelpContext

Message


EDimIndexError methods

EDimIndexError	Alphabetically

In EDimIndexError

~EDimIndexError

EDimIndexError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDimIndexError methods

EDimIndexError	By object

~EDimIndexError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDimIndexError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDimIndexError::EDimIndexError

EDimIndexError	See also

EDimIndexError creates a new EDimIndexError object.

__fastcall EDimIndexError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EDimIndexError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EDimIndexError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EDimIndexError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EDimIndexError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EDimIndexError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDimIndexError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EDimIndexError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext){ }

Description

EDimIndexError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDimIndexError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EDimIndexError::~EDimIndexError

EDimIndexError	See also

~EDimIndexError frees the memory associated with the EDimIndexError object.

__fastcall virtual ~EDimIndexError(void) { }

Description

Do not call ~EDimIndexError directly. Instead, use the delete keyword on the object, which causes ~EDimIndexError to be invoked automatically.


Hierarchy

TObject

Exception


EDimIndexError example

EDimIndexError


TDimensionItem

Hierarchy	Properties	Methods	See also

TDimensionItem is the base class for objects that represent dimensions and summaries in a crosstabulated data store.

Unit

mxcommon

Description

Use TDimensionItem as a base class when defining classes that represent the fields used by a crosstabulated data store. TDimensionItem describes a field from the data set used by a crosstabulated data store and the role that field plays in the data store. Crosstabulated data stores automatically create dimension items to represent the fields that make up their multidimensional arrays of summary values.

TDimensionItem has a single descendant, TCubeDim, that enhances the dimension item with the ability to represent date ranges.


TDimensionItem properties

TDimensionItem	Alphabetically	Legend

In TDimensionItem

ActiveFlag

BaseName

DerivedFrom

DimensionType

FieldName

FieldType

Format

Name

Derived from TCollectionItem

Collection

DisplayName

ID

Index


TDimensionItem properties

TDimensionItem	By object	Legend

ActiveFlag

BaseName

Collection

DerivedFrom

DimensionType

DisplayName

FieldName

FieldType

Format

ID

Index

Name


TDimensionItem::ActiveFlag

TDimensionItem	See also

Indicates whether the dimension item is stored in the cache of a crosstabulated data store.

enum TActiveFlags { diActive, diAsNeeded, diInactive };

__property TActiveFlags ActiveFlag = {read=FActiveFlag, write=SetActiveFlag, nodefault};

Description

Set ActiveFlag to diActive when it is critical that the dimension item is available at all times. Set ActiveFlag to diAsNeeded instead if the dimension item is used less frequently. The decision cube swaps dimension items with Active set to diAsNeeded in and out of the cache depending on when they are actually used, in order to conserve memory. Set ActiveFlag to diInactive to collapse the multidimensional array maintained by the data store so that it does not include the dimension item. When ActiveFlag is diInactive, the data store can not provide information about the dimension item to a decision source object.

The memory needs of a crosstabulated data store increase geometrically with each active dimension that is included. Memory needs increase linearly with each active summary that is included. Applications must find the best balance between the performance benefit of caching many dimensions and summaries so that they are immediately available to decision controls, and the need to keep the size of the cached multidimensional data array small enough so that it does not consume inordinate amounts of memory.


TDimensionItem::BaseName

TDimensionItem	See also

Specifies the FieldName of the database field that is represented by or summarized in the dimension item.

__property System::AnsiString BaseName = {read=FBaseName, write=SetBaseName};

Description

Use BaseName to identify the field whose values underlie the dimension item. If the dimension item represents a dimension then BaseName is the name of the field that corresponds to the dimension. Otherwise, BaseName is the field name of the field whose values are summarized by the dimension item.

Note:	Basename is a fully qualified SQL selector. Table and field names must be correctly punctuated, including quotations.


TDimensionItem::DerivedFrom

TDimensionItem	See also

Specifies the index of a dimension item from which a derived value is calculated.

__property int DerivedFrom = {read=FDerivedFrom, write=SetDerivedFrom, nodefault};

Description

Read DerivedFrom to determine whether the dimension item represents a field from the dataset of its decision cube. Dimension items that represent averages do not come directly from the dataset, but are derived from count and summary fields that appear in the dataset. When a derived average dimension item is created, DerivedFrom is set to the index of the count or summary dimension item. The corresponding summary or count dimension item is located by matching the BaseName property when the derived values are calculated.


TDimensionItem::DimensionType

TDimensionItem	See also

Indicates the use of the dimension item.

enum TDimFlags { dimDimension, dimSum, dimCount, dimAverage, dimMin, dimMax, dimGenericAgg, dimUnknown};

__property TDimFlags DimensionType = {read=FType, write=SetType, nodefault};

Description

Read DimensionType to determine whether the dimension item represents a dimension of the multidimensional array maintained by the crosstabulated data store or whether the dimension item represents a summary field that supplies the values to the cells of the multidimensional array. If the dimension item represents a summary, DimensionType also indicates the type of summary.

Do not set DimensionType if the dimension item represents a field from a query. The value of DimensionType is set automatically to reflect the semantics of the query if the crosstabulated data store that uses the dimension item is bound to a query. If the data store is bound to another type of data set, set DimensionType to a value that indicates the use of the dimension item in the multidimensional array.

DimensionType can have any of the following values:

Value	Meaning

dimDimension	The dimension item represents a dimension of the multidimensional array.

dimSum	The dimension item is a summary that represents the sum of a field value.

dimCount	The dimension item is a summary that represents the count of nonblank field values.

dimAverage	The dimension item is a summary that represents the average field value.

dimMin	The dimension item is a summary that represents the minimum field value. (not currently implemented)

dimMax	The dimension item is a summary that represents the maximum field value. (not currently implemented)

dimGenericAgg	The dimension item is some other type of summary.


TDimensionItem::FieldName

TDimensionItem	See also

Specifies the name of the field that the dimension item represents.

__property System::AnsiString Fieldname = {read=FFieldName, write=SetFieldName};

Description

Read FieldName to determine the name of the field on which the dimension item is based. FieldName is the same as the FieldName property of the TField object the dimension represents.

Do not set the FieldName property. Its value is set automatically to indicate the field from the dataset that supplies the values for the dimension item. To change the name used by decision controls that display the dimension, use the Name property instead.


TDimensionItem::FieldType

TDimensionItem	See also

Indicates the data type of the field that the dimension item represents.

enum TFieldType { ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat, ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc, ftBlob, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary, ftCursor };

__property Db::TFieldType FieldType = {read=FFieldType, write=SetFieldType, nodefault};

Description

Read FieldType to determine the type of data that makes up the values of the dimension item. FieldType is the same as the DataType property of the corresponding TField object from the dataset of the crosstabulated data store.

Do not set the FieldType property. The value of FieldType is set automatically to reflect the type of data provided by the dimension item.


TDimensionItem::Format

TDimensionItem	See also

Indicates how field values are formatted on dimensions that represent numeric or temporal data.

__property System::AnsiString Format = {read=FFormat, write=SetFormat};

Description

Set Format on dimension items that represent numeric or temporal fields. The format specifiers that make up the Format string depend on the field type.

See the FormatFloat runtime library function for a description of the format specifiers for a numeric field. See the FormatDateTime runtime library function for a description of the format specifiers for a temporal field.

Decision controls that display value names read the value of Format, but can override it when formatting field values.


TDimensionItem::Name

TDimensionItem	See also

Denotes the name of a dimension or summary.

__property System::AnsiString Name = {read=FName, write=SetName};

Description

Set Name to change the name provided by the GetDimensionName or GetSummaryName method of the crosstabulated data store. Decision controls that display dimension names read the value of Name, but can override it.


TDimensionItem methods

TDimensionItem	Alphabetically

In TDimensionItem

~TDimensionItem

IsDimension

IsSummary

TDimensionItem

Derived from TCollectionItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDimensionItem methods

TDimensionItem	By object

~TDimensionItem

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

IsDimension

IsSummary

MethodAddress

MethodName

NewInstance

SafeCallException

TDimensionItem


TDimensionItem::IsDimension

TDimensionItem	See also

Indicates whether the dimension item represents a dimension.

bool __fastcall IsDimension(void);

Description

Call IsDimension to determine the use of the dimension item. IsDimension returns true if the dimension item represents one of the dimensions of the multidimensional array maintained by a crosstabulated data store. IsDimension returns false if the dimension item represents a field that provides the summary values that fill the cells of the multidimensional array.


TDimensionItem::IsSummary

TDimensionItem	See also

Indicates whether the dimension item represents a summary.

bool __fastcall IsSummary(void);

Description

Call IsSummary to determine the use of the dimension item. IsSummary returns true if the dimension item represents a field that provides the summary values that fill the cells of the multidimensional array maintained by a crosstabulated data store. IsSummary returns false if the dimension item represents a one of the dimensions of the multidimensional array.


TDimensionItem::TDimensionItem

TDimensionItem

Creates a new TDimensionItem object.

__fastcall virtual TDimensionItem(Classes::TCollection* Collection);

Description

Do not create instances of TDimensionItem. It is intended only as a base class.


TDimensionItem::~TDimensionItem

TDimensionItem

~TDimensionItem frees the memory associated with the TDimensionItem object.

__fastcall virtual ~TDimensionItem(void) { }

Description

Do not call ~TDimensionItem directly. Instead, use the delete keyword on the object, which causes ~TDimensionItem to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


TDimensionItems

Hierarchy	Properties	Methods	See also

TDimensionItems is the base class for objects that represent dimension maps.

Unit

mxcommon

Description

Use TDimensionItems as a base class when defining classes that represent the dimension map of a crosstabulated data store. TDimensionItems represents a collection of TDimensionItem objects, where each TDimensionItem corresponds to a field from the data set of the crosstabulated data store.

TDimensionItems has a single descendant, TCubeDims, that adds additional functionality to handle dimension maps that include date ranges.


TDimensionItems properties

TDimensionItems	Alphabetically	Legend

In TDimensionItems

ActiveDimensionCount

ActiveSummaryCount

DimensionCount

Items

SummaryCount

Derived from TCollection

Count

ItemClass


TDimensionItems properties

TDimensionItems	By object	Legend

ActiveDimensionCount

ActiveSummaryCount

Count

DimensionCount

ItemClass

Items

SummaryCount


TDimensionItems::ActiveDimensionCount

TDimensionItems	See also

Indicates the number of dimension items that represent active dimensions in the crosstabulated data store.

__property int ActiveDimensionCount = {read=GetActiveDimCount, nodefault};

Description

Read ActiveDimensionCount to determine the number of dimensions in the multidimensional data array cached by the data store. The memory requirements of the cached array go up exponentially with each active dimension, so ActiveDimensionCount provides a rough sense of the size of the cached array.

ActiveDimensionCount is the number of dimension items in the Items array that have their DimensionType property set to dimDimension and their Active property set to true. Change ActiveDimensionCount indirectly by changing the Active property on dimension items with DimensionType values of dimDimension.

The DimensionCount property indicates the total number of dimension items with DimensionType set to dimDimension. It provides an upper limit to the ActiveDimensionCount property.


TDimensionItems::ActiveSummaryCount

TDimensionItems	See also

Indicates the number of dimension items that represent active summaries in the crosstabulated data store.

__property int ActiveSummaryCount = {read=GetActiveSumCount, nodefault};

Description

Read ActiveSummaryCount to determine the number of summaries in the cells of the multidimensional data array cached by the data store. The memory requirements of the cached array go up linearly with each active summary. ActiveSummaryCount is the number of different summaries that can be made available to decision controls.

ActiveSummaryCount is the number of dimension items in the Items array that don’t have their DimensionType property set to dimDimension and do have their Active property set to true. Change ActiveSummaryCount indirectly by changing the Active property on dimension items with DimensionType values other than dimDimension.

The SummaryCount property indicates the total number of dimension items that do not have DimensionType set to dimDimension. It provides an upper limit to the ActiveSummaryCount property.


TDimensionItems::DimensionCount

TDimensionItems	See also

Indicates the number of dimension items in the Items array with DimensionType set to dimDimension.

__property int DimensionCount = {read=GetDimCount, nodefault};

Description

Read DimensionCount to determine the number of potential dimensions for the multidimensional data array cached by the data store. DimensionCount reflects the number of unsummarized fields in the data set of the crosstabulated data store. While the data store can make any of these dimensions available, usually only a subset are active at any time, in order to limit memory consumption. The ActiveDimensionCount property gives the number of dimensions that are currently active.


TDimensionItems::Items

TDimensionItems	See also

Lists all dimension items maintained by the TDimensionItems object.

__property TDimensionItem* Items[int Index] = {read=GetDimensionItem, write=SetDimensionItem};

Description

Use Items to access individual dimension items maintained by the TDimensionItems object. The first dimension item has an Index of 0, the second dimension item has an Index of 1, and so on.

Each dimension item in the Items array represents a field from the data set of a crosstabulated data store. Each dimension item represents either a dimension (a field over which data is summarized), or a summary (a value summarized over the dimensions).

Note:	Do not change the Items property. The set of items in the Items array is set automatically to represent the fields from the data set. The properties of individual dimension items within the Items array may be changed to specify whether the dimension items should be cached by the data store, to change the name used when displaying the dimension items, and so on.


TDimensionItems::SummaryCount

TDimensionItems	See also

Indicates the number of dimension items in the Items array with DimensionType set to a value other than dimDimension.

__property int SummaryCount = {read=GetSumCount, nodefault};

Description

Read SummaryCount to determine the number of potential summaries that could be stored in the cells of the multidimensional data array cached by the data store. SummaryCount reflects the number of summarized fields in the data set of the crosstabulated data store. If memory is a serious concern, the data store can make any of these summaries inactive. The ActiveSummaryCount property gives the number of summaries that are currently active.


TDimensionItems methods

TDimensionItems	Alphabetically

In TDimensionItems

~TDimensionItems

Add

AddDerivedField

AlreadyExists

Assign

AverageFieldCheck

TDimensionItems

Derived from TCollection

BeginUpdate

Clear

EndUpdate

FindItemID

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDimensionItems methods

TDimensionItems	By object

~TDimensionItems

Add

AddDerivedField

AlreadyExists

Assign

AverageFieldCheck

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDimensionItems


TDimensionItems.Add

TDimensionItems	See also

Adds a dimension item to the end of the Items array.

HIDESBASE TDimensionItem* __fastcall Add(void);

Description

Do not call the Add method to add dimension items to a TDimensionItems object. The dimension items are added automatically to reflect the fields in the data set of the associated crosstabulated data store.

Add adds a new dimension item to the collection and returns the new dimension item.


TDimensionItems::AddDerivedField

TDimensionItems	See also

Adds a derived average summary to the end of the Items array.

enum TDimFlags { dimDimension, dimSum, dimCount, dimAverage, dimMin, dimMax, dimGenericAgg, dimUnknown};

int __fastcall AddDerivedField(int Index, TDimFlags dimType);

Description

Summaries that represent average values are not taken directly from the source dataset of a decision cube, but are derived from count summaries and summation summaries. AddDerivedField creates a dimension item for an average summary. The Index parameter specifies the index of an existing dimension item whose BaseName property specifies the field over which averages should be computed. AddDerivedField checks for the summary dimension items needed to derive the average. If both an average and a summation are available for the base field, AddDerivedField creates the average summary dimension item. AddDerivedField returns true if the dimension item is successfully created, false otherwise.

Note:	The dimType parameter is currently ignored. Descendants of AddDerivedField can override this method to derive other types of dimension items. In this case, dimType should specify the type of derived dimension item that should be created. When overriding AddDerivedField, call the parent class’s method if dimType is dimAverage.


TDimensionItems::AlreadyExists

TDimensionItems	See also

Indicates whether a dimension item with specified properties already exists in the Items property array.

enum TDimFlags { dimDimension, dimSum, dimCount, dimAverage, dimMin, dimMax, dimGenericAgg, dimUnknown};

bool __fastcall AlreadyExists(System::AnsiString BaseName, TDimFlags sType);

Description

Call AlreadyExists to determine whether there is a dimension item in the Items property array with the BaseName property equal to the BaseName parameter and the DimensionType property equal to the sType parameter.


TDimensionItems::Assign

TDimensionItems	See also

Copies the list of dimension items from another TDimensionItems object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign calls the parent class’s method to copy the properties of the Source parameter. The parent method will copy properties from any object that implements an AssignTo method that can copy to a TDimensionItems object.


TDimensionItems::AverageFieldCheck

TDimensionItems	See also

Determines whether the necessary summary dimension items over a base dimension exist so that a dimension item of type dimAverage can be computed.

bool __fastcall AverageFieldCheck(int Index, int &SumIndex, int &CountIndex);

Description

Call AverageFieldCheck to ensure that the necessary summary dimension items exist for creating an average summary. The Index parameter specifies an existing dimension item whose BaseName property specifies the field over which the average should be computed. The SumIndex and CountIndex parameters return the summation and count dimension items that can be used to compute average values.


TDimensionItems::TDimensionItems

TDimensionItems	See also

Creates an instance of TDimensionItems.

__fastcall TDimensionItems(Classes::TPersistent* Owner, System::TMetaClass* ItemClass);

Description

Applications should not need to call the constructor of TDimensionItems. TCustomDataStore objects create TDimensionItems objects to implement their DimensionMap property.


TDimensionItems::~TDimensionItems

TDimensionItems

~TDimensionItems frees the memory associated with the TDimensionItems object.

__fastcall virtual ~TDimensionItems(void) { }

Description

Applications should not need to call the destructor of TDimensionItems. TCustomDataStore objects delete TDimensionItems objects when they are through with them.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


EDimensionMapError

Hierarchy	Properties	Methods	See also

EDimensionMapError is the exception class for when the dataset of a decision cube does not have the proper format.

Unit

mxcommon

Description

EDimensionMapError is thrown when the dataset of a decision cube does not contain any summary values, contains only summary values, or is a query that does not contain the appropriate grouping.


EDimensionMapError properties

EDimensionMapError	Alphabetically

Derived from Exception

HelpContext

Message


EDimensionMapError properties

EDimensionMapError	By object

HelpContext

Message


EDimensionMapError methods

EDimensionMapError	Alphabetically

In EDimensionMapError

~EDimensionMapError

EDimensionMapError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDimensionMapError methods

EDimensionMapError	By object

~EDimensionMapError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDimensionMapError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDimensionMapError::EDimensionMapError

EDimensionMapError	See also

EDimensionMapError creates a new EDimensionMapError object.

__fastcall EDimensionMapError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EDimensionMapError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EDimensionMapError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EDimensionMapError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EDimensionMapError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EDimensionMapError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDimensionMapError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EDimensionMapError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EDimensionMapError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDimensionMapError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EDimensionMapError::~EDimensionMapError

EDimensionMapError	See also

~EDimensionMapError frees the memory associated with the EDimensionMapError object.

__fastcall virtual ~EDimensionMapError(void) { };

Description

Do not call ~EDimensionMapError directly. Instead, use the delete keyword on the object, which causes ~EDimensionMapError to be invoked automatically.


Hierarchy

TObject

Exception


EDimensionMapError example

EDimensionMapError


TDirectoryListBox

Hierarchy	Properties	Methods	Events 	See also

TDirectoryListBox represents a list box control that is aware of the directory structure of the current drive.

Unit

filectrl

Description

TDirectoryListBox implements the generic behavior introduced in TCustomListBox. TDirectoryListBox publishes many of the properties inherited from TCustomListBox, and introduces any new behavior to allow the user to change directories or drives.

For other specialized list boxes see other descendant classes of TCustomListBox, or derive from TCustomListBox.


TDirectoryListBox properties

TDirectoryListBox	Alphabetically	Legend

In TDirectoryListBox

CaseSensitive

Directory

DirLabel

Drive

FileList

PreserveCase

Derived from TCustomListBox

Canvas

Columns

IntegralHeight

ItemHeight

ItemIndex

Items

SelCount

Selected

TopIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDirectoryListBox properties

TDirectoryListBox	By object	Legend

Align

BoundsRect

Brush

Canvas

CaseSensitive

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

Directory

DirLabel

DragCursor

DragMode

Drive

Enabled

FileList

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IntegralHeight

ItemHeight

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

PreserveCase

SelCount

Selected

ShowHint

Showing

TabOrder

TabStop

Tag

Top

TopIndex

VCLComObject

Visible

Width

WindowProc


TDirectoryListBox::CaseSensitive

TDirectoryListBox	See also

Determines if the disk system supports case-sensitive directory information.

__property bool CaseSensitive = {read=FCaseSensitive, nodefault};

Description

Use CaseSensitive to find whether or not the current file system supports case-sensitive file names. CaseSensitive returns true if it does and false if it does not.


TDirectoryListBox::Directory

TDirectoryListBox	See also 	Example

Determines the current directory for the directory list box control.

__property System::AnsiString Directory = {read=FDirectory, write=SetDirectory};

Description

The directory list box displays the value of the Directory property as the current directory in the list box. Examine the example to see how a directory list box and a file list box can work together through their Directory properties.

Note:	If the form contains a file list box, set the FileList property to have the file list box automatically display the files from the directory specified by the Directory property.


TDirectoryListBox::DirLabel

TDirectoryListBox	See also 	Example

Provides a simple way to display the current directory as the caption of a label control.

__property Stdctrls::TLabel* DirLabel = {read=FDirLabel, write=SetDirLabel};

Description

Use DirLabel to specify the label to update with the current directory. When the current directory changes in the directory list box, the change is reflected in the caption of the label.


TDirectoryListBox::Drive

TDirectoryListBox	See also 	Example

Determines the drive for which the list box displays the directory structure.

__property char Drive = {read=GetDrive, write=SetDrive, nodefault};

Description

When the value of Drive changes, the Directory value changes also to the current directory on the specified drive.


TDirectoryListBox::FileList

TDirectoryListBox	See also 	Example

Provides a simple way to connect a directory list box with a file list box.

__property TFileListBox* FileList = {read=FFileList, write=SetFileListBox};

Description

Use FileList to specify the file list box in which to display the files of the current directory.

Set FileList to the file list box that will display the files in the directory. Set the Directory property of the directory list box.


TDirectoryListBox::PreserveCase

TDirectoryListBox	See also

Indicates whether the file system preserves the case of file names when writing to disk.

__property bool PreserveCase = {read=FPreserveCase, nodefault};

Description

Use PreserveCase to find whether or not the current file system preserves the case-sensitivity of file names. PreserveCase returns true if it does and false if it does not.


TDirectoryListBox events

TDirectoryListBox	Alphabetically	Legend

In TDirectoryListBox

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDirectoryListBox events

TDirectoryListBox	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDirectoryListBox::OnChange

TDirectoryListBox 	Example

Occurs when the user selects a new directory with the mouse or keyboard when the user moves the selection bar and presses enter.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Use OnChange to write an event handler to process an action when a new directory is selected.


TDirectoryListBox methods

TDirectoryListBox	Alphabetically

In TDirectoryListBox

~TDirectoryListBox

DisplayCase

FileCompareText

GetItemPath

OpenCurrent

TDirectoryListBox

Update

Derived from TCustomListBox

Clear

ItemAtPos

ItemRect

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDirectoryListBox methods

TDirectoryListBox	By object

~TDirectoryListBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DisplayCase

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FileCompareText

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetItemPath

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

ItemAtPos

ItemRect

MethodAddress

MethodName

NewInstance

OpenCurrent

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDirectoryListBox

Update

UpdateControlState


TDirectoryListBox::TDirectoryListBox

TDirectoryListBox	See also

Creates and intitializes a directory list box.

__fastcall virtual TDirectoryListBox(Classes::TComponent* AOwner);

__fastcall TDriveComboBox(HWND ParentWindow) : Stdctrls::TCustomComboBox(ParentWindow) { }

Description

Call TDirectoryListBox indirectly, using the new keyword, to instantiate a directory list box at runtime. For directory list boxes created at design time, TDirectoryListBox is called automatically.

Pass a single Component as a parameter to provide the TDirectoryListBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the directory list box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

TDirectoryListBox allocates memory for a directory list box, and calls the parent object's constructor. Then it sets the following properties:

•	Width to 145.

•	Style to lbOwnerDrawFixed.

•	Sorted to false.

Then it creates and loads bitmaps for the Open, Close and Current folders and initializes the directory to the current directory on the default drive.


TDirectoryListBox::~TDirectoryListBox

TDirectoryListBox	See also

Disposes of an instance of a directory list box.

__fastcall virtual ~TDirectoryListBox(void);

Description

Do not call ~TDirectoryListBox directly in an application. Instead, use the delete keyword on the object, which causes ~TDirectoryListBox to be invoked automatically.

~TDirectoryListBox frees the bitmaps used for the Open, Close, and Current folders, and then calls the parent object's destructor.


TDirectoryListBox::DisplayCase

TDirectoryListBox	See also

Preserves or converts the case of the string passed to it.

System::AnsiString __fastcall DisplayCase(const System::AnsiString S);

Description

DisplayCase converts S to all lowercase, using the currently installed language driver, if neither PreserveCase nor CaseSensitive are true. Otherwise, it returns S unmodified.


TDirectoryListBox::FileCompareText

TDirectoryListBox	See also

Compares two strings taking into account the case sensitivity of the file system.

int __fastcall FileCompareText(const System::AnsiString A, const System::AnsiString B);

Description

FileCompareText compares the strings passed to it as A and B, if CaseSensitive is false. Otherwise, it uses AnsiCompareStr to compare the strings.


TDirectoryListBox::GetItemPath

TDirectoryListBox	See also 	Example

Returns the path of a directory in the directory list box.

System::AnsiString __fastcall GetItemPath(int Index);

Description

Use GetItemPath to get the path of a directory by specifying the directory with the Index value. The first directory in the list has an index value of 0.


TDirectoryListBox::OpenCurrent

TDirectoryListBox 	Example

Opens the selected directory.

void __fastcall OpenCurrent(void);

Description

OpenCurrent opens the directory selected in the directory list box, as if the user had double-clicked the directory.


TDirectoryListBox::Update

TDirectoryListBox 	Example

Refreshes the directory list.

HIDESBASE void __fastcall Update(void);

Description

Call Update to refresh the directory list of the directory list box control when new directories have been created or existing directories deleted.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomListBox


 TWebDispatcher

Hierarchy	Properties	Methods	Events

TWebDispatcher passes HTTP request message on to the appropriate action items that assemble a response.

Unit

httpapp

Description

Use TWebDispatcher to convert an ordinary data module to a Web module. Add a TWebDispatcher object to an existing data module that contains other non-visual components and business rules for the Web application. Then delete the automatically generated Web module from the Web application and replace it with the data module that now contains the Web dispatcher.

TWebDispatcher enables the Web server application to respond to HTTP request messages. Only one Web dispatcher can be added to an application. This is why the automatically generated Web module, which is a type of Web dispatcher, must be deleted from the Web application before the data module containing TWebDispatcher can be added.

The TWebDispatcher object manages a collection of action items which know how to respond to HTTP request messages. View, add and delete the action items managed by the dispatcher using the Action editor which is opened by double clicking on the TWebDispatcher icon.

TWebDispatcher publishes some of the properties and events introduced by TCustomWebDispatcher, but introduces no new properties, events, or methods of its own.


TWebDispatcher properties

TWebDispatcher	Alphabetically	Legend

Derived from TCustomWebDispatcher

Action

Actions

Request

Response

Derived from TDataModule

DesignOffset

DesignSize

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TWebDispatcher properties

TWebDispatcher	By object	Legend

Action

Actions

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

DesignOffset

DesignSize

Name

Owner

Request

Response

Tag

VCLComObject


TWebDispatcher events

TWebDispatcher	Alphabetically	Legend

Derived from TCustomWebDispatcher

AfterDispatch

BeforeDispatch

Derived from TDataModule

OnCreate

OnDestroy


TWebDispatcher events

TWebDispatcher	By object	Legend

AfterDispatch

BeforeDispatch

OnCreate

OnDestroy


TWebDispatcher methods

TWebDispatcher	Alphabetically

In TWebDispatcher

~TWebDispatcher

TWebDispatcher

Derived from TCustomWebDispatcher

ActionByName

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TWebDispatcher methods

TWebDispatcher	By object

~TWebDispatcher

ActionByName

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TWebDispatcher


TWebDispatcher::TWebDispatcher

TWebDispatcher

Creates a new TWebDispatcher object.

__fastcall virtual TWebDispatcher(Classes::TComponent* AOwner) : Httpapp::TCustomWebDispatcher(AOwner) { }

__fastcall TWebDispatcher(Classes::TComponent* AOwner, int Dummy) : Httpapp:: TCustomWebDispatcher(AOwner, Dummy) { }

Description

Most applications will not need to create a web dispatcher programmatically. Web dispatchers placed in data modules at design time are created automatically.

When creating a web dispatcher at runtime, use the new keyword, passing in the arguments of the desired constructor. The first argument to the constructor indicates the owner of the web dispatcher, which is responsible for freeing it. The second parameter (in the second syntax) is a dummy parameter that serves only to distinguish that constructor from the first constructor syntax. If a second argument is provided, the web dispatcher does not load its properties or owned objects when it is read into memory.


TWebDispatcher::~TWebDispatcher

TWebDispatcher

~TWebDispatcher frees the memory associated with the TWebDispatcher object.

__fastcall virtual ~TWebDispatcher(void) { }

Description

Do not call ~TWebDispatcher directly. Instead, use the delete keyword on the object, which causes ~TWebDispatcher to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataModule

TCustomWebDispatcher


TDisplayDim

Hierarchy	Properties	Methods	See also

TDisplayDim represents a dimension in a decision grid.

Unit

mxgrid

Description

Use TDisplayDim to set the properties of a dimension in a decision grid. Decision grids maintain a collection of TDisplayDim objects that describe the dimension labels that run along their left and top edges. The properties of TDisplayDim can be used to make the labels for a single dimension stand out, or to turn on or off subtotals over the dimension.


TDisplayDim properties

TDisplayDim	Alphabetically	Legend

In TDisplayDim

Alignment

Color

DisplayName

FieldName

Format

Subtotals

Derived from TCollectionItem

Collection

ID

Index


TDisplayDim properties

TDisplayDim	By object	Legend

Alignment

Collection

Color

DisplayName

FieldName

Format

ID

Index

Subtotals


TDisplayDim::Alignment

TDisplayDim 	See also

Specifies the placement of values within the label cells.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, nodefault};

Description

Set Alignment to determine how the values of the dimension field are aligned in the label cells. Alignment can be one of the following values:

Value	Meaning

taLeftJustify	Values appear lined up along the left edge of the label cells.

taRightJustify	Values appear lined up along the right edge of the label cells.

taCenter	Values are centered in the label cells.


TDisplayDim::Color

TDisplayDim	See also

Specifies the background color of the label cells for the dimension.

__property Graphics::TColor Color = {read=FColor, write=SetColor, nodefault};

Description

Set Color to override the LabelColor property of the decision grid for the labels along a single dimension. Cells that display the field values along this dimension use Color for the background color.


TDisplayDim::DisplayName

TDisplayDim	See also

Describes the dimension in the caption cell.

__property System::AnsiString DisplayName = {read=FName, write=SetName};

Description

Set DisplayName to the name that appears in the caption cell that displays the name of this dimension. DisplayName overrides the name of the dimension returned by the decision source in its GetDimensionName method.


TDisplayDim::FieldName

TDisplayDim	See also

Names the field in the underlying data set that the dimension represents.

__property System::AnsiString FieldName = {read=FFieldName, write=SetFieldName};

Description

Read FieldName to determine the name of the field on which the dimension item is based. FieldName is the same as the FieldName property of the TField object for the field in the dataset.

Note:	Do not change the FieldName property. Changing the FieldName property loses the link to the underlying field in the data set.


TDisplayDim::Format

TDisplayDim	See also

Specifies the format for value labels along the dimension.

__property System::AnsiString Format = {read=FFormat, write=SetFormat};

Description

Set Format to specify how the values of the dimension field should be formatted into display labels. The format specifiers that make up the Format string depend on the field type.

See the FormatFloat runtime library function for a description of the format specifiers for a numeric field. See the FormatDateTime runtime library function for a description of the format specifiers for a temporal field. Format has no effect on other field types.


TDisplayDim::SubTotals

TDisplayDim	See also

Indicates whether the grid should display subtotals over the dimension.

__property bool Subtotals = {read=FSubs, write=SetSubs, nodefault};

Description

Set SubTotals to true to add a row or column of subtotals following the last value of the dimension. The subtotal row or column contains values of the summary field summarized over all values in the dimension. Set SubTotals to false to omit the subtotal row or column at the end of the dimension.

To turn subtotals on or off for all dimensions in the grid at once, use the Totals property of the decision grid.


TDisplayDim methods

TDisplayDim	Alphabetically

In TDisplayDim

~TDisplayDim

TDisplayDim

Derived from TCollectionItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDisplayDim methods

TDisplayDim	By object

~TDisplayDim

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDisplayDim


TDisplayDim::TDisplayDim

TDisplayDim 	See also

Creates a new TDisplayDim object.

__fastcall virtual TDisplayDim(Classes::TCollection* Collection);

Description

Use the new keyword when creating instances of TDisplayDim.


TDisplayDim::~TDisplayDim

TDisplayDim 	See also

~TDisplayDim frees the memory associated with the TDisplayDim object.

__fastcall virtual ~TDisplayDim(void) { }

Description

Do not call ~TDisplayDim directly. Instead, use the delete keyword on the object, which causes ~TDisplayDim to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem

TDimensionItem


TDisplayDims

Hierarchy	Properties	Methods	See also

TDisplayDims represents a collection of TDisplayDim objects.

Unit

mxgrid

Description

Use TDisplayDims to describe the dimensions of a decision grid. Each TDisplayDim object maintained by TDisplayDims corresponds to a field from the decision source. Decision grids use TDisplayDims to specify the appearance of the dimension labels that appear along the left and top edges of the grid.


TDisplayDims properties

TDisplayDims	Alphabetically	Legend

In TDisplayDims

Items

Derived from TCollection

Count

ItemClass


TDisplayDims properties

TDisplayDims	By object	Legend

Count

ItemClass

Items


TDisplayDims::Items

TDisplayDims	See also

Lists the TDisplayDim objects in the collection.

__property TDisplayDim* Items[int Index] = {read=GetDisplayDim, write=SetDisplayDim};

Description

Use Items to access the properties of the TDisplayDim objects maintained by TDisplayDims. The TDisplayDim objects in the Items array should correspond exactly to the dimensions of the decision source used by the decision control associated with the TDisplayDims object. Do not directly change the elements of the Items array. To rearrange the display dimensions, use the SwapDimIndexes method of the decision source. To hide display dimensions, use the CloseDimIndexRight method of the decision source. To show hidden dimensions, use the OpenDimIndexLeft or OpenDimIndexRight method of the decision source.


TDisplayDims methods

TDisplayDims	Alphabetically

In TDisplayDims

~TDisplayDims

TDisplayDims

Derived from TCollection

Add

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDisplayDims methods

TDisplayDims	By object

~TDisplayDims

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDisplayDims


TDisplayDims::TDisplayDims

TDisplayDims

Creates a new TDisplayDims object.

__fastcall TDisplayDims(TCustomDecisionGrid* Grid, System::TMetaClass* ItemClass);

Description

Do not create instances of TDisplayDims. They are created automatically by the decision grids that use them.


TDisplayDims::~TDisplayDims

TDisplayDims

~TDisplayDims frees the memory associated with the TDisplayDims object.

__fastcall virtual ~TDisplayDims(void) { }

Description

Do not call ~TDisplayDims directly. Instead, use the delete keyword on the object, which causes ~TDisplayDims to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


TDragObject

Hierarchy	Methods	See also

TDragObject is a base class used for managing drag and drop operations.

Unit

controls

Description

Use TDragObject to implement drag and drop of object’s data, instead of the control containing the data by deriving from TDragObject and overriding its virtual methods as needed. Create the custom drag object in the OnStartDrag event. Use the public IsDragObject function within a target’s OnDragOver event when accepting a drag drop.

TDragObject allows more flexible drag and drop handling. Normally, the Source parameter of the OnDragOver and OnDragDrop events is the control that stars the drag operation. If multiple controls of differing kinds need to start a drag of the same kind of data (for example, a file name, text, or a dollar amount), the source would need support for each kind of control. A drag object allows the target to need only know how to handle a drag object as a source since each of the source controls can create the same kind of drag object in their OnStartDrag events. The OnDragOver and OnDragDrop events can tell if the source is a drag object, as opposed to the control, by calling IsDragObject.

Drag objects can be dragged between multiple DLLs as well as inside the main EXE. This is useful if you are not using packages but still want drag operations to function from forms implemented in EXEs to forms implemented in DLLs.


TDragObject methods

TDragObject	Alphabetically	Legend

In TDragObject

~TDragObject

Finished

GetDragCursor

GetDragImages

GetName

HideDragImage

Instance

ShowDragImage

TDragObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDragObject methods

TDragObject	By object	Legend

~TDragObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Finished

Free

FreeInstance

GetDragCursor

GetDragImages

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetName

HideDragImage

InheritsFrom

InitInstance

Instance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

ShowDragImage

TDragObject


TDragObject::Finished

TDragObject	See also

Responds when the mouse is released indicating the drag operation is complete.

virtual void __fastcall Finished(System::TObject* Target, int X, int Y, bool Accepted);

Description

Finished does nothing by default, but can be overridden to provide more meaningful behavior. The Target is the object that accepted the drag. Target can be NULL. Accepted returns true if the Target accepted the drag and drop. Finished is overridden and implemented in TDragControlObject.


TDragObject::GetDragCursor

TDragObject	See also

Indicates which cursor should be displayed in response to mouse moves.

virtual TCursor __fastcall GetDragCursor(bool Accepted, int X, int Y);

Description

When the mouse is moved, GetDragCursor is called automatically.  The Accepted parameter indicates whether the object under the mouse accepts the drag. The X and Y parameters represent the current position of the mouse. The TCursor value returned by GetDragCursor is used to indicate the current drag cursor.

GetDragCursor returns crDrag to when Accepted is true, crNoDrop otherwise.


TDragObject::GetDragImages

TDragObject	See also

Returns an image list containing the image to be displayed while dragging.

virtual TCustomImageList* __fastcall GetDragImages(void);

Description

GetDragImages is called at the beginning of a drag and drop operation. TDragObject::GetDragImages returns NULL, meaning that only the cursor is used to indicate the drag operation.

In descendant classes, the image list normally contains only one image, and the drag object automatically creates and maintains the image list.


TDragObject::GetName

TDragObject	See also

Returns a name string identifying the drag operation.

virtual System::AnsiString __fastcall GetName();

Description

By default GetName returns the name of the class, but can be overridden to return a more meaningful string.


TDragObject::HideDragImage

TDragObject	See also

Provides the interface for a method that hides the current drag image.

virtual void __fastcall HideDragImage(void);

Description

Because TDragObject does not implement drag images (relying only on the cursor) HideDragImage does nothing. Descendant classes override HideDragImage to hide the drag image provided by the GetDragImages method.


TDragObject::Instance

TDragObject	See also

Returns the instance (module) handle of the EXE or DLL that created the drag object.

virtual int __fastcall Instance(void);

Description

Use Instance to obtain the instance handle for loading a resource, such as a cursor, associated with the drag object.  See the example for the Cursors property of TScreen for an example of using the instance handle to load a cursor.


TDragObject::ShowDragImage

TDragObject	See also

Provides the interface for a method that hides the current drag image.

virtual void __fastcall ShowDragImage(void);

Description

Because TDragObject does not implement drag images (relying only on the cursor) ShowDragImage does nothing. Descendant classes override ShowDragImage to show the drag image provided by the GetDragImages method.


TDragObject::TDragObject

TDragObject

Creates a new TDragObject object.

__fastcall TDragObject(void) : System::TObject() { }

Description

Call TDragObject indirectly, using the new keyword, to implement drag and drop of an object’s data.


TDragObject::~TDragObject

TDragObject

Frees the memory associated with the TDragObject object.

__fastcall virtual ~TDragObject(void) { }

Description

Do not call ~TDragObject directly. Instead, use the delete keyword on the object, which causes ~TDragObject to be invoked automatically.


Scope

Protected


Hierarchy

TObject


 TDrawGrid

Hierarchy	Properties	Methods	Events	See also

TDrawGrid represents a grid control that displays information in column and row format.

Unit

grids

Description

Add a TDrawGrid object to a form to present arbitrary information in a tabular format. TDrawGrid provides many properties to control the appearance of the grid, as well as events and methods that take advantage of the tabular organization of the grid in responding to user actions.

TDrawGrid introduces several events and methods to allow applications to customize the appearance and behavior of the grid.

If the cells of the grid contain text strings that represent objects, consider using a TStringGrid object instead. If the grid displays field values from the records in a dataset, use TDBGrid instead.


TDrawGrid properties

TDrawGrid	Alphabetically	Legend

Derived from TCustomGrid

BorderStyle

Col

ColCount

ColWidths

DefaultColWidth

DefaultDrawing

DefaultRowHeight

EditorMode

FixedColor

FixedCols

FixedRows

GridHeight

GridLineWidth

GridWidth

LeftCol

Options

Row

RowCount

RowHeights

ScrollBars

Selection

TabStops

TopRow

VisibleColCount

VisibleRowCount

Derived from TCustomControl

Canvas

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDrawGrid properties

TDrawGrid	By object	Legend

Align

BorderStyle

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Col

ColCount

Color

ColWidths

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DefaultColWidth

DefaultDrawing

DefaultRowHeight

DesignInfo

DragCursor

DragMode

EditorMode

Enabled

FixedColor

FixedCols

FixedRows

Font

GridHeight

GridLineWidth

GridWidth

Handle

Height

HelpContext

Hint

Left

LeftCol

Name

Options

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

Row

RowCount

RowHeights

ScrollBars

Selection

ShowHint

Showing

TabOrder

TabStop

TabStops

Tag

Top

TopRow

VCLComObject

Visible

VisibleColCount

VisibleRowCount

Width

WindowProc


TDrawGrid events

TDrawGrid	Alphabetically	Legend

In TDrawGrid

OnColumnMoved

OnDrawCell

OnGetEditMask

OnGetEditText

OnRowMoved

OnSelectCell

OnSetEditText

OnTopLeftChanged

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TDrawGrid events

TDrawGrid	By object	Legend

OnClick

OnColumnMoved

OnDblClick

OnDragDrop

OnDragOver

OnDrawCell

OnEndDrag

OnEnter

OnExit

OnGetEditMask

OnGetEditText

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnRowMoved

OnSelectCell

OnSetEditText

OnStartDrag

OnTopLeftChanged


TDrawGrid::OnColumnMoved

TDrawGrid	See also

Occurs immediately after the position of a column changes.

__property TMovedEvent OnColumnMoved = {read=FOnColumnMoved, write=FOnColumnMoved};

Description

Use OnColumnMoved to perform special processing when the position of a grid column changes. Columns can be moved programmatically or by user manipulation. The FromIndex parameter is the old index of the column, and the ToIndex parameter is the new index. OnColumnMoved does not occur unless the Options property includes goColMoving.


TDrawGrid::OnDrawCell

TDrawGrid	See also 	Example

Occurs when a cell in the grid needs to be drawn.

__property TDrawCellEvent OnDrawCell = {read=FOnDrawCell, write=FOnDrawCell};

Description

Write an OnDrawCell event handler to draw the contents all the cells in the grid. Draw on the cell using the methods of the Canvas property. The Rect parameter indicates the location of the cell on the canvas. The Col and Row parameters indicate the column and row indexes of the cell that should be drawn. The State parameter indicates whether the cell has input focus, whether the cell is selected, and whether the cell is a fixed (nonscrolling) cell.

If the OnDrawCell event handler is not assigned, all cells in the draw grid will appear empty. If the DefaultDrawing property is true, the draw grid paints the background color of the cell before the OnDrawCell event, and draws a focus rectangle around the selected cell after the OnDrawCell event handler finishes drawing the contents of the cell. If the DefaultDrawing property is false, the OnDrawCell event handler should paint the background of the cell and provide all visual indication of selection and focus.


TDrawGrid::OnGetEditMask

TDrawGrid	See also 	Example

Occurs when the in-place editor requests an edit mask.

__property TGetEditEvent OnGetEditMask = {read=FOnGetEditMask, write=FOnGetEditMask};

Description

Write an OnGetEditMask event handler to provide the in-place editor with an edit mask that describes the valid input strings a user can type into a cell. Set the Value parameter to the string that describes the edit mask for the cell specified by the ACol and ARow parameters. If the cell does not have an edit mask, set the Value parameter to an empty string.

OnGetEditMask does not occur unless the Options property includes goEditing.


TDrawGrid::OnGetEditText

TDrawGrid	See also 	Example

Occurs when the in-place editor requests the value of a cell.

__property TGetEditEvent OnGetEditText = {read=FOnGetEditText, write=FOnGetEditText};

Description

Write an OnGetEditText event handler to provide the in-place editor with a string representing the contents of the cell. Set the Value parameter to the string for the cell specified by the ACol and ARow parameters. When the cell enters edit mode, the contents of the cell are drawn as the Value string returned by the OnGetEditText event handler. This image need not match the appearance of the cell when it is not in edit mode, which is drawn using the OnDrawCell event handler.

OnGetEditText does not occur unless the Options property includes goEditing.


TDrawGrid::OnRowMoved

TDrawGrid	See also 	Example

Occurs immediately after the position of a row changes.

__property TMovedEvent OnRowMoved = {read=FOnRowMoved, write=FOnRowMoved};

Description

Write an OnRowMoved event handler to provide special processing whenever a row in the grid changes position. Rows can be moved programmatically or by user manipulation. The FromIndex parameter is the old index of the row, and the ToIndex parameter is the new index. OnRowMoved does not occur unless the Options property includes goRowMoving.


TDrawGrid::OnSelectCell

TDrawGrid	See also 	Example

Occurs before a cell in the grid is selected.

__property TSelectCellEvent OnSelectCell = {read=FOnSelectCell, write=FOnSelectCell};

Description

Write an OnSelectCell event handler to specify whether any particular cell in the grid can be selected. The Col and Row parameters indicate the column and row indexes of the cell that is about to be selected. Set the CanSelect parameter to false to prevent the cell being selected.


TDrawGrid::OnSetEditText

TDrawGrid	See also

Occurs when the user has finished editing the value of a cell.

__property TSetEditEvent OnSetEditText = {read=FOnSetEditText, write=FOnSetEditText};

Description

Write an OnSetEditText event handler to perform any special processing of the text edited by the user in an in-place editor. For example, use the OnSetEditText event to retrieve and store the value of a cell so that it can be displayed in an OnDrawCell event handler. The Value parameter is the new value for the cell specified by the ACol and ARow parameters.

OnSetEditText does not occur unless the Options property includes goEditing.


TDrawGrid::OnTopLeftChanged

TDrawGrid	See also

Occurs immediately after the TopRow property or the LeftCol property changes.

__property Classes::TNotifyEvent OnTopLeftChanged = {read=FOnTopLeftChanged, write=FOnTopLeftChanged};

Description

Use OnTopLeftChanged to perform special processing when the non-fixed cells in the grid are scrolled.


TDrawGrid methods

TDrawGrid	Alphabetically	Legend

In TDrawGrid

~TDrawGrid

CellRect

ColumnMoved

DrawCell

GetEditMask

GetEditText

MouseToCell

RowMoved

SelectCell

SetEditText

TDrawGrid

TopLeftChanged

Derived from TCustomGrid

MouseCoord

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDrawGrid methods

TDrawGrid	By object	Legend

~TDrawGrid

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CellRect

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ColumnMoved

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

DrawCell

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetEditMask

GetEditText

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

MouseCoord

MouseToCell

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

RowMoved

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectCell

SendToBack

SetBounds

SetEditText

SetFocus

SetTextBuf

Show

TDrawGrid

TopLeftChanged

Update

UpdateControlState


TDrawGrid::CellRect

TDrawGrid	See also	Example

Returns the screen coordinates of a cell in the grid.

HIDESBASE Windows::TRect __fastcall CellRect(int ACol, int ARow);

Description

Call CellRect to obtain the boundaries, in pixels, of the cell in the column and row indicated by the ACol and ARow parameters. The top left cell is specified when ACol and ARow are set to zero.

If the indicated cell is not visible, CellRect returns an empty rectangle.


TDrawGrid::ColumnMoved

TDrawGrid	See also

Generates an OnColumnMoved event.

DYNAMIC void __fastcall ColumnMoved(int FromIndex, int ToIndex);

Description

ColumnMoved is called immediately after a column in the grid has moved. It overrides the parent class's method to generate an OnColumnMoved event. Descendants of TDrawGrid can override this method to make internal adjustments or to block the OnColumnMoved event.


TDrawGrid::DrawCell

TDrawGrid	See also

Generates an OnDrawCell event.

virtual void __fastcall DrawCell(int ACol, int ARow, const Windows::TRect &ARect, TGridDrawState AState);

Description

DrawCell is called automatically whenever a cell in the grid is drawn. If the DefaultDrawing property is true, the background of the cell is painted before DrawCell is called, and the 3D effects of the fixed cells or the focus rectangle around the focused cell are drawn after DrawCell. Descendants of TDrawGrid can override this method to draw the contents of the cell or to block the OnDrawCell event.


TDrawGrid::GetEditMask

TDrawGrid	See also

Generates an OnGetEditMask event.

DYNAMIC System::AnsiString __fastcall GetEditMask(int ACol, int ARow);

Description

The inplace editor calls GetEditMask to obtain any input mask associated with the cell specified by the ACol and ARow parameters. GetEditMask returns the Value parameter set by the OnGetEditMask event handler. If there is no OnGetEditMask event handler, GetEditMask returns an empty string, indicating that there is no edit mask.


TDrawGrid::GetEditText

TDrawGrid	See also

Generates an OnGetEditText event.

DYNAMIC System::AnsiString __fastcall GetEditText(int ACol, int ARow);

Description

The inplace editor calls GetEditText to obtain the text for the indicated cell. GetEditText returns the Value parameter set by the OnGetEditText event handler. If there is no OnGetEditText event handler, GetEditText returns an empty string.


TDrawGrid::MouseToCell

TDrawGrid	See also 	Example

Returns the column and row of the cell at the position with screen coordinates (X,Y).

void __fastcall MouseToCell(int X, int Y, int &ACol, int &ARow);

Description

Call MouseToCell to convert from grid-relative screen coordinates to row and column indexes. The X and Y parameters are the screen coordinates of the point to be converted. MouseToCell returns the ACol parameter as the number of the column over the point (X,Y), and the ARow parameter as the number of the row.

Usually the MouseToCell method is used in a mouse event handler, which supplies the mouse coordinates as the X and Y parameters of the method call.


TDrawGrid::RowMoved

TDrawGrid	See also

Generates an OnRowMoved event.

DYNAMIC void __fastcall RowMoved(int FromIndex, int ToIndex);

Description

RowMoved is called immediately after a row in the grid changes position. It overrides the parent class's method to generate an OnRowMoved event. Descendants of TDrawGrid can override this method to make internal adjustments or to block the OnRowMoved event.


TDrawGrid::SelectCell

TDrawGrid	See also

Determines whether a particular cell in the grid can be selected.

virtual bool __fastcall SelectCell(int ACol, int ARow);

Description

Grid controls call SelectCell internally before attempting to move selection to a the cell identified by the ACol and ARow parameters. ACol and ARow are the column and row indexes for the cell, where the first column has index 0, and the top row has index 0.

SelectCell generates an OnSelectCell event. This method then returns true, unless the OnSelectCell event handler indicates that the cell should not be selected. Descendants of TDrawGrid can override this method to check the properties of the information displayed in the cell or block the OnSelectCell event.


TDrawGrid::SetEditText

TDrawGrid	See also

Generates an OnSetEditText event.

DYNAMIC void __fastcall SetEditText(int ACol, int ARow, const System::AnsiString Value);

Description

SetEditText is called by the inplace editor so that the grid can store the new value for the current cell. SetEditText overrides the parent class's method to generate an OnSetEditText event. Descendants of TDrawGrid can override this method to update an internal representation of the cell’s value, or to block the OnSetEditText event.


TDrawGrid::TopLeftChanged

TDrawGrid	See also

Generates an OnTopLeftChanged event.

DYNAMIC void __fastcall TopLeftChanged(void);

Description

Grid controls call TopLeftChanged internally, whenever the LeftCol or TopRow property changes. After calling the parent class's method to update the position of the inplace editor, TopLeftChanged generates an OnTopLeftChanged event.


TDrawGrid::TDrawGrid

TDrawGrid	See also

Creates a new TDrawGrid object.

__fastcall virtual TDrawGrid(Classes::TComponent* AOwner) : Grids::TCustomGrid(AOwner) { }

__fastcall TDrawGrid(HWND ParentWindow) : Grids::TCustomGrid(ParentWindow) { }

Description

Do not call TDrawGrid directly. Instead, use the new keyword to create a reference to a TDrawGrid object at runtime.


TDrawGrid::~TDrawGrid

TDrawGrid

Frees the memory associated with the TDrawGrid object.

__fastcall virtual ~TDrawGrid(void) { }

Description

Do not call ~TDrawGrid directly. Instead, use the delete keyword on the object, which causes ~TDrawGrid to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGrid


TDragControlObject

Hierarchy	Properties	Methods	See also

TDragControlObject object provides for normal drag and drop operations.

Unit

controls

Description

TDragControlObject object is used to perform normal drag and drop operations within C++Builder. When TDragControlObject is used the OnDragOver and OnDragDrop events receive the control being dragged as the Sender, instead of the drag object itself.


TDragControlObject properties

TDragControlObject	Alphabetically	Legend

In TDragControlObject

Control


TDragControlObject properties

TDragControlObject	By object	Legend

Control


TDragControlObject::Control

TDragControlObject	See also

The Control property returns the control that is being dragged in the drag and drop operation.

__property TControl* Control = {read=FControl};

Description

Control is useful in determining which control is currently being dragged.


TDragControlObject methods

TDragControlObject	Alphabetically	Legend

In TDragControlObject

~TDragControlObject

Finished

GetDragCursor

GetDragImages

HideDragImage

ShowDragImage

TDragControlObject

Derived from TDragObject

GetName

Instance

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDragControlObject methods

TDragControlObject	By object	Legend

~TDragControlObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Finished

Free

FreeInstance

GetDragCursor

GetDragImages

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetName

HideDragImage

InheritsFrom

InitInstance

Instance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

ShowDragImage

TDragControlObject


TDragControlObject::TDragControlObject

TDragControlObject	See also

Creates an instance of the TDragControlObject and stores a reference to the control that is being dragged.

__fastcall TDragControlObject(TControl* AControl);

Description

Do not call the TDragControlObject method for a TDragControlObject directly. Instead, use the new keyword.


TDragControlObject::Finished

TDragControlObject	See also

Finished ends a drag and drop operation and calls the OnEndDrag event handler.

virtual void __fastcall Finished(System::TObject* Target, int X, int Y, bool Accepted);

Description

Accepted indicates whether the Target control at X, Y position accepts the drag and drop operation. If the control does not accept the drag and drop, the control’s DragCanceled method is called before the OnEndDrag event handler.


TDragControlObject::GetDragCursor

TDragControlObject	See also

GetDragCursor returns the correct drag cursor that should be displayed at the X, Y position for the drag and drop operation.

virtual TCursor __fastcall GetDragCursor(bool Accepted, int X, int Y);

Description

If the control at the X, Y position accepts the drag (in an OnDragOver event handler), the drag object sets the drag cursor to the control's DragCursor property; otherwise, it displays the crNoDrop cursor.


TDragControlObject::GetDragImages

TDragControlObject	See also

GetDragImages returns the control's image list containing the image to be displayed while dragging.

virtual TCustomImageList* __fastcall GetDragImages(void);

Description

GetDragImages calls a control’s GetDragImages method. An image list normally contains only one image, and the VCL automatically creates and maintains the image list. For most controls in the VCL GetDragImages returns NULL unless the method has been overridden to do otherwise as in TCustomTreeView.


TDragControlObject::HideDragImage

TDragControlObject	See also

The HideDragImage method hides the image used in the drag cursor.

virtual void __fastcall HideDragImage(void);

Description

If the control being dragged contains an image list containing an image for dragging, it will be hidden. This allows control over when a drag image is displayed.


TDragControlObject::ShowDragImage

TDragControlObject	See also

The ShowDragImage method shows the image used in the drag cursor.

virtual void __fastcall ShowDragImage(void);

Description

If the control being dragged contains an image list containing an image for dragging, it will be show. This allows control over when a drag image is shown.


Accessibility

Read-only


TDragControlObject::~TDragControlObject

TDragControlObject

Frees the memory associated with the TDragControlObject object.

__fastcall virtual ~TDragControlObject(void) { }

Description

Do not call ~TDragControlObject directly. Instead, use the delete keyword on the object, which causes ~TDragControlObject to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TDragObject


TDriveComboBox

Hierarchy	Properties	Methods	Events	See also

TDriveComboBox implements a specialized combo box that displays all the drives available when the application runs.

Unit

filectrl

Description

Add TDriveComboBox to a form to allow users to select a drive. Use TDriveComboBox along with TFileListBox, TFilterComboBox, and TDirectoryListBox to add full file selection capabilities to a form.

To add a standard Windows 95 file open or save dialog to an application, use TOpenDialog or TSaveDialog instead.


TDriveComboBox properties

TDriveComboBox	Alphabetically	Legend

In TDriveComboBox

DirList

Drive

TextCase

Derived from TCustomComboBox

Canvas

DroppedDown

ItemIndex

Items

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDriveComboBox properties

TDriveComboBox	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DirList

DragCursor

DragMode

Drive

DroppedDown

Enabled

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

TextCase

Top

VCLComObject

Visible

Width

WindowProc


TDriveComboBox::DirList

TDriveComboBox	See also 	Example

Connects the drive combo box to a directory list box.

__property TDirectoryListBox* DirList = {read=FDirList, write=SetDirListBox};

Description

Set DirList to a directory list box control that should update when the user changes the drive. When a new drive is selected in the drive combo box, the specified directory list box updates to display the directory structure and the current directory on the new drive.

Note:	If the form contains a file list box as well, it can be updated automatically using the FileList property of the directory list box object.


TDriveComboBox::Drive

TDriveComboBox	See also 	Example

Indicates the currently selected drive displayed in the edit portion of the combo box.

__property char Drive = {read=FDrive, write=SetDrive, nodefault};

Description

Set Drive to initialize the combo box to a particular drive. Read Drive to obtain the drive that was selected by the user.

When the user uses the drive combo box to select a new drive, the selected drive becomes the value of the Drive property. The value of the Text property also changes to the new volume name when the Drive property value changes.


TDriveComboBox::TextCase

TDriveComboBox	See also

Determines if the volume name in the Text property appears in uppercase or lowercase.

enum TTextCase { tcLowerCase, tcUpperCase };

__property TTextCase TextCase = {read=FTextCase, write=SetTextCase, default=0};

Description

Set TextCase to the case that should be used to represent the drive letter. These are the possible values:

Value	Meaning

tcLowerCase	The volume name specified in the Text property is displayed in lowercase letters.

tcUpperCase	The volume name specified in the Text property is displayed in uppercase letters.

Note:	Changes made to the TextCase property at design time don’t appear until the application runs.


TDriveComboBox events

TDriveComboBox	Alphabetically	Legend

Derived from TCustomComboBox

OnChange

OnDropDown

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDriveComboBox events

TDriveComboBox	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDropDown

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnStartDrag


TDriveComboBox methods

TDriveComboBox	Alphabetically

In TDriveComboBox

~TDriveComboBox

TDriveComboBox

Derived from TCustomComboBox

Clear

SelectAll

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDriveComboBox methods

TDriveComboBox	By object

~TDriveComboBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDriveComboBox

Update

UpdateControlState


TDriveComboBox::TDriveComboBox

TDriveComboBox	See also

Creates and initializes an instance of TDriveComboBox.

__fastcall virtual TDriveComboBox(Classes::TComponent* AOwner);

__fastcall TDriveComboBox(HWND ParentWindow) : Stdctrls::TCustomComboBox(ParentWindow) { }

Description

Do not call TDriveComboBox directly when creating a drive combo box at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created drive combo box. TDriveComboBox objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the drive combo box with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the drive combo box in a non-VCL window. This syntax is used when the TDriveComboBox object is implemented as an ActiveX control that is embedded in a non-VCL window.

After allocating the memory for the combo box, TDriveComboBox fills the combo box with all the drives on the system, and initializes the Drive property to the current drive.


TDriveComboBox::~TDriveComboBox

TDriveComboBox	See also

Destroys an instance of TDriveComboBox.

__fastcall virtual ~TDriveComboBox(void);

Description

Do not call ~TDriveComboBox directly in an application. Instead, use the delete keyword, which takes an indirect reference to a TDriveComboBox instance.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomComboBox


TDataSetDesigner

Hierarchy	Properties	Methods	See also

TDataSetDesigner is the base class for all dataset designers.

Unit

db

Description

Use TDataSetDesigner when defining a design-time editor, such as the Fields editor, that enables a developer to specify the fields that belong to a dataset at design time. The dataset designer is specified as the designer property of a dataset that uses it to enable design-time specification of its structure.


TDataSetDesigner properties

TDataSetDesigner	Alphabetically 	Legend

In TDataSetDesigner

DataSet


TDataSetDesigner properties

TDataSetDesigner	By object 	Legend

DataSet


TDataSetDesigner::DataSet

TDataSetDesigner 	See also

The DataSet property provides a reference to the dataset currently being designed.

__property TDataSet* DataSet = {read=FDataSet};

Description

Use DataSet to access the dataset, if any, that is being designed. When the user specifies changes in the dataset designer, the changes can be made to the dataset specified by the DataSet property.


TDataSetDesigner methods

TDataSetDesigner	Alphabetically

In TDataSetDesigner

~TDataSetDesigner

BeginDesign

DataEvent

EndDesign

TDataSetDesigner

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDataSetDesigner methods

TDataSetDesigner	By object

~TDataSetDesigner

BeginDesign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DataEvent

DefaultHandler

Dispatch

EndDesign

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDataSetDesigner


TDataSetDesigner::BeginDesign

TDataSetDesigner 	See also

BeginDesgin ensures that the dataset is not active while design changes are made.

void __fastcall BeginDesign(void);

Description

Call BeginDesign before changing the structure of the associated dataset.  BeginDesign deactivates the dataset and disables any associated controls until the EndDesign method is called.


TDataSetDesigner::TDataSetDesigner

TDataSetDesigner	See also

TDataSetDesigner creates and initializes an instance of TDataSetDesigner.

__fastcall TDataSetDesigner(TDataSet* DataSet);

Description

Call TDataSetDesigner from the component editor of a specialized dataset to create an instance of the dataset designer. TDataSetDesigner initializes the DataSet property of the dataset designer and the Designer property of the dataset.


TDataSetDesigner::DataEvent

TDataSetDesigner

DataEvent provides the interface for a method that can respond to data events.

virtual void __fastcall DataEvent(TDataEvent Event, int Info);

Description

Call DataEvent to pass information about data events to the dataset designer.  The Event parameter specifies the type of event that is occurring.  Use the Info parameter to specify additional information about the event.  The value of the Info parameter depends on the type of data event.

The DataEvent method for TDataSetDesigner does nothing when informed of a data event.  Override this method to allow the data set designer to respond to different types of events.


TDataSetDesigner::~TDataSetDesigner

TDataSetDesigner	See also

~TDataSetDesigner disposes of an instance of TDataSetDesigner.

__fastcall virtual ~TDataSetDesigner(void);

Description

Do not call the ~TDataSetDesigner method directly.  Instead, when freeing the dataset designer from a component editor, use the Free method.  Free checks that the dataset designer is not already freed, and only then calls ~TDataSetDesigner.

~TDataSetDesigner sets the Designer property of the associated dataset to NULL before destroying the instance of TDataSetDesigner.


TDataSetDesigner::EndDesign

TDataSetDesigner 	See also

EndDesign reactivates the dataset if it was active when designing began.

void __fastcall EndDesign(void);

Description

Call EndDesign when changes to the dataset are complete.  EndDesign re-enables all controls that use the dataset and resets the Active property of the dataset to the value it help when BeginDesign was called.


Accessibility

Read-only


Hierarchy

TObject


TDataSetTableProducer

Hierarchy	Properties	Methods	Events	See also

TDataSetTableProducer assembles a sequence of HTML commands to display the records from a dataset in a tabular format.

Unit

dbweb

Description

Use TDataSetTableProducer to produce an HTML table for the records of a TDataSet object. If the dataset is a query that requires input parameters from an HTTP request message, use TQueryTableProducer instead.

TDataSetTableProducer allows an application to create images of a dataset for an HTTP response message.


TDataSetTableProducer properties

TDataSetTableProducer	Alphabetically	Legend

In TDataSetTableProducer

DataSet

Derived from TDSTableProducer

Caption

CaptionAlignment

Columns

Editor

Footer

Header

MaxRows

RowAttributes

TableAttributes

Derived from TCustomContentProducer

Dispatcher

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDataSetTableProducer properties

TDataSetTableProducer	By object	Legend

Caption

CaptionAlignment

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataSet

DesignInfo

Dispatcher

Editor

Footer

Header

MaxRows

Name

Owner

RowAttributes

TableAttributes

Tag

VCLComObject


TDataSetTableProducer::DataSet

TDataSetTableProducer	See also

Specifies the TDataSet object where the dataset table producer looks for the records it displays in an HTML table.

__property Db::TDataSet* DataSet = {read=GetDataSet, write=SetDataSet};

Description

Set DataSet to specify the dataset that contains the records to be displayed in an HTML table. Use DataSet to set the dataset for the TDataSetTableProducer rather than the DataSource property. Dataset table producers do not use an external TDataSource object, but generate their own data source internally.

The individual field bindings specified by the THTMLTableColumn objects in the Columns property refer to fields in DataSet.


TDataSetTableProducer events

TDataSetTableProducer	Alphabetically	Legend

Derived from TDSTableProducer

OnCreateContent

OnFormatCell

OnGetTableCaption


TDataSetTableProducer events

TDataSetTableProducer	By object	Legend

OnCreateContent

OnFormatCell

OnGetTableCaption


TDataSetTableProducer methods

TDataSetTableProducer	Alphabetically

In TDataSetTableProducer

~TDataSetTableProducer

Content

TDataSetTableProducer

Derived from TDSTableProducer

BeginUpdate

EndUpdate

Derived from TCustomContentProducer

ContentFromStream

ContentFromString

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDataSetTableProducer methods

TDataSetTableProducer	By object

~TDataSetTableProducer

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Content

ContentFromStream

ContentFromString

DefaultHandler

DestroyComponents

Destroying

Dispatch

EndUpdate

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TDataSetTableProducer


TDataSetTableProducer::Content

TDataSetTableProducer	See also

Returns the HTML representation of the records in the dataset.

virtual System::AnsiString __fastcall Content(void);

Description

Call Content to retrieve the HTML representation specified by the properties of the TDataSetTableProducer object. Content calls the OnCreateContent event handler. If the OnCreateContent event handler indicates that the Content method should continue, Content returns the Header property, followed by an HTML table image of the records in the dataset, followed by the Footer property. If the OnCreateContent event handler indicates that the Content method should not continue, Content returns an empty string.

The string returned by Content can be used as the Content property of the response to an HTTP request message.


TDataSetTableProducer::TDataSetTableProducer

TDataSetTableProducer

Creates a new TDataSetTableProducer object.

__fastcall virtual TDataSetTableProducer(Classes::TComponent* AOwner) : Dbweb::TDSTableProducer(AOwner) { }

Description

Do not call TDataSetTableProducer directly when creating a table producer at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TDataSetTableProducer object. TDataSetTableProducer objects placed in a web module at design time are created automatically.

Pass a single Component as a parameter to provide the TDataSetTableProducer object with an Owner that is responsible for freeing it.


TDataSetTableProducer::~TDataSetTableProducer

TDataSetTableProducer

Frees the memory associated with the TDataSetTableProducer object.

__fastcall virtual ~TDataSetTableProducer(void) { }

Description

Do not call ~TDataSetTableProducer directly. Instead, use the delete keyword on the object, which causes ~TDataSetTableProducer to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomContentProducer

TDSTableProducer


 TDSTableProducer

Hierarchy	Properties	Methods	Events	See also

TDSTableProducer is the abstract base class for objects that produce a set of HTML commands to display the records from a dataset in a tabular format.

Unit

dbweb

Description

Use TDSTableProducer as a base class when defining a class that produces an HTML table that represents the records of a dataset. TDSTableProducer introduces many properties to describe the appearance and data binding of the HTML table. The events and methods of TDSTableProducer allow an application to retrieve the database information and produce the HTML commands that describe the table.


TDSTableProducer properties

TDSTableProducer	Alphabetically	Legend

In TDSTableProducer

Caption

CaptionAlignment

Columns

DataLink

DataSet

DataSource

Editor

Footer

Header

InternalDataSource

MaxRows

RowAttributes

TableAttributes

Derived from TCustomContentProducer

Dispatcher

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDSTableProducer properties

TDSTableProducer	By object	Legend

Caption

CaptionAlignment

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataLink

DataSet

DataSource

DesignInfo

Dispatcher

Editor

Footer

Header

InternalDataSource

MaxRows

Name

Owner

RowAttributes

TableAttributes

Tag

VCLComObject


TDSTableProducer::Caption

TDSTableProducer	See also

Specifies the caption string that appears with the HTML table.

__property System::AnsiString Caption = {read=FCaption, write=SetCaption};

Description

Set Caption to add a caption to the HTML table that represents the dataset. Caption indicates the text that should appear inside the HTML CAPTION tag.


TDSTableProducer::CaptionAlignment

TDSTableProducer	See also

Specifies where the Caption string should appear relative to the HTML table.

__property THTMLCaptionAlignment CaptionAlignment = {read=FCaptionAlignment, write=SetCaptionAlignment, default=0};

Description

Set CaptionAlignment to specify whether the Caption should appear above or below the HTML table. CaptionAlignment can be one of the following values:

Value	Meaning

caDefault	The Web browser can position the caption where it wants.

caTop	The caption should appear above the HTML table.

caBottom	The caption should appear below the HTML table.

CaptionAlignment is the value of the ALIGN option on the HTML CAPTION tag.


TDSTableProducer::Columns

TDSTableProducer	See also 	Example

Describes the field bindings and display attributes of the columns in the HTML table.

__property THTMLTableColumns* Columns = {read=FColumns, write=SetColumns, stored=StoreColumns};

Description

Use Columns to read or set the field bindings and display attributes of the columns in the HTML table. Each THTMLTableColumn object specifies the display attributes of the corresponding column. Each column object also specifies the name of the field the column represents. The field binding of a column designates a field within the dataset specified by the DataSet property.

Columns can be set at design time through a property editor, or programmatically at runtime.


TDSTableProducer::DataLink

TDSTableProducer	See also

Manages the link to the dataset.

__property THTTPDataLink* DataLink = {read=FDataLink};

Description

Applications cannot use the DataLink property. It is exposed as a protected property so that descendant HTML producers can customize their response to data events.


TDSTableProducer::DataSet

TDSTableProducer	See also

Specifies the dataset from which the data in the HTML table is taken.

__property Db::TDataSet* DataSet = {read=GetDataSet, write=SetDataSet};

Description

Set DataSet to specify where the TDSTableProducer should look for the data it displays in the HTML table. The individual field bindings specified by the THTMLTableColumn objects in the Columns property refer to fields in DataSet.

Specify the data binding of a TDSTableProducer using the DataSet property rather than through a DataSource property. TDSTableProducer objects do not use an external TDataSource object.


TDSTableProducer::DataSource

TDSTableProducer	See also

Represents the link to the DataSet of the TDSTableProducer.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Do not use the DataSource property. The data source of a TDSTableProducer object is an internally generated TDataSource object that is used for internal interfaces that do not work directly with a TDataSet object.

The InternalDataSource property provides read-only access to the data source represented by DataSource.


TDSTableProducer::Editor

TDSTableProducer

Writes changes made in the property editor at design time to the TDSTableProducer object.

__property TDSTableProducerEditor* Editor = {read=FEditor, write=FEditor};

Description

Descendants of TDSTableProducer set the Editor property to the TDSTableProducerEditor object that connects their implementation with a common property editor. Editor allows a single property editor to represent the properties of different table producers.


TDSTableProducer::Footer

TDSTableProducer	See also

Specifies a set of HTML commands that appear in the HTML document following the HTML table.

__property Classes::TStrings* Footer = {read=FFooter, write=SetFooter};

Description

Set Footer to embed the representation of DataSet in a larger document. The Content method of TDSTableProducer descendants returns any Header commands, followed by the HTML table that represents the DataSet, followed by any Footer commands.


TDSTableProducer::Header

TDSTableProducer	See also

Specifies a set of HTML commands that appear in the HTML document preceding the HTML table.

__property Classes::TStrings* Header = {read=FHeader, write=SetHeader};

Description

Set Header to embed the representation of DataSet in a larger document. The Content method of TDSTableProducer descendants returns any Header commands, followed by the HTML table that represents the DataSet, followed by any Footer commands.


TDSTableProducer::InternalDataSource

TDSTableProducer	See also

Represents the link to the dataset.

__property Db::TDataSource* InternalDataSource = {read=FInternalDataSource};

Description

Descendants of TDSTableProducer read InternalDataSource to access the properties and methods of the data source. Unlike other data-aware components, TDSTableProducer does not use an external TDataSource object.


TDSTableProducer::MaxRows

TDSTableProducer	See also

Specifies the maximum number of rows that appear in the HTML table.

__property int MaxRows = {read=FMaxRows, write=SetMaxRows, default=20};

Description

Set MaxRows to change the upper limit on the size of the HTML table produced to represent the DataSet. MaxRows is initialized to 20.

If DataSet contains more than MaxRows records, only the first MaxRows records appear in the HTML commands produced by Content. If DataSet contains fewer than MaxRows records, the HTML table produced by TDSTableProducer will contain only enough rows to display all the records in DataSet.


TDSTableProducer::RowAttributes

TDSTableProducer	See also

Specifies the display attributes of all the rows in the HTML table.

__property Httpapp::THTMLTableRowAttributes* RowAttributes = {read=FRowAttributes, write=SetRowAttributes};

Description

Set RowAttributes to a THTMLTableRowAttributes object that describes the display attributes of the rows in the HTML table. Setting RowAttributes calls the Assign method of the THTMLTableRowAttributes object stored internally by TDSTableProducer. Thus, the memory for any row attributes object assigned to the RowAttributes property is never owned or freed by TDSTableProducer.

Note:	Not all the properties of the row attributes object are copied when one row attributes object is assigned to another. To ensure that all the attributes represented by RowAttributes are set appropriately, read RowAttributes and set the individual properties of the THTMLTableRowAttributes object.


TDSTableProducer::TableAttributes

TDSTableProducer	See also

Specifies the display attributes that pertain to the entire HTML table produced by TDSTableProducer.

__property Httpapp::THTMLTableAttributes* TableAttributes = {read=FTableAttributes, write=SetTableAttributes}

Description

Set TableAttributes to a THTMLTableAttributes object that describes the display attributes for the HTML TABLE tag. Setting TableAttributes calls the Assign method of the THTMLTableAttributes object stored internally by TDSTableProducer. Thus, the memory for any table attributes object assigned to the TableAttributes property is never owned or freed by TDSTableProducer.

Note:	Not all the properties of the table attributes object are copied when one table attributes object is assigned to another. To ensure that all the attributes represented by TableAttributes are set appropriately, read TableAttributes and set the individual properties of the THTMLTableAttributes object.


TDSTableProducer events

TDSTableProducer	Alphabetically	Legend

In TDSTableProducer

OnCreateContent

OnFormatCell

OnGetTableCaption


TDSTableProducer events

TDSTableProducer	By object	Legend

OnCreateContent

OnFormatCell

OnGetTableCaption


TDSTableProducer::OnCreateContent

TDSTableProducer	See also

Occurs in descendants of TDSTableProducer when the Content method needs to generate the HTML table image.

typedef void __fastcall (__closure *TCreateContentEvent) (System::TObject* Sender, bool &Continue);

__property TCreateContentEvent OnCreateContent = {read=FOnCreateContent, write=FOnCreateContent};

Description

Write an OnCreateContent event handler to conditionally prevent the Content method from producing any HTML commands. Set the Continue parameter to false to make Content return an empty string.


TDSTableProducer::OnFormatCell

TDSTableProducer	See also

Occurs when the HTML for a specified cell specified is about to be generated.

enum THTMLAlign { haDefault, haLeft, haRight, haCenter };

enum THTMLVAlign { haVDefault, haTop, haMiddle, haBottom, haBaseline };

typedef void __fastcall (__closure *THTMLFormatCellEvent) (System::TObject* Sender, int CellRow, int CellColumn, System::AnsiString &BgColor, Httpapp::THTMLAlign &Align, Httpapp::THTMLVAlign &VAlign, System::AnsiString &CustomAttrs, System::AnsiString &CellData);

__property THTMLFormatCellEvent OnFormatCell = {read=FOnFormatCell, write=FOnFormatCell};

Description

Write an OnFormatCell event handler to change the appearance or contents of individual cells in the HTML table from the default values produced by TDSTableProducer. CellRow and CellColumn specify the cell that is about to be generated, where the table header is CellRow 0, and the first column is CellColumn 0.

BgColor, Align, VAlign, and CustomAttrs represent the default display properties for the cell, taken from the THTMLTableColumn object for the column in which the cell appears. See the corresponding entries for these properties of the THTMLTableColumn object for more information on these values.

CellData is the text that appears in the cell, taken from the field object for the column. The OnFormatCell event handler can change any or all of these values to specify the way the cell should appear in the final HTML table.


TDSTableProducer::OnGetTableCaption

TDSTableProducer	See also

Occurs when the HTML table producer is about to generate the HTML for the table caption.

__property THTMLGetTableCaptionEvent OnGetTableCaption = {read=FOnGetTableCaption, write=FOnGetTableCaption};

Description

Write an OnGetTableCaption event handler to change the value or placement of the HTML table caption. The Caption and Alignment parameters are originally set to the values of the Caption and CaptionAlignment properties, respectively. The OnGetTableCaption event handler can change these values to alter the caption for the HTML table returned by the Content method.


TDSTableProducer methods

TDSTableProducer	Alphabetically	Legend

In TDSTableProducer

~TDSTableProducer

AcquireLayoutLock

BeginLayout

BeginUpdate

DefineFieldMap

DoCreateContent

DoFormatCell

DoGetCaption

EndLayout

EndUpdate

GetDataSet

GetDataSource

LayoutChanged

LinkActive

Notification

SetColumns

SetDataSet

SetDataSource

StoreColumns

TDSTableProducer

Derived from TCustomContentProducer

Content

ContentFromStream

ContentFromString

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDSTableProducer methods

TDSTableProducer	By object	Legend

~TDSTableProducer

AcquireLayoutLock

Assign

BeginLayout

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Content

ContentFromStream

ContentFromString

DefaultHandler

DefineFieldMap

DestroyComponents

Destroying

Dispatch

DoCreateContent

DoFormatCell

DoGetCaption

EndLayout

EndUpdate

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetDataSet

GetDataSource

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

LayoutChanged

LinkActive

MethodAddress

MethodName

NewInstance

Notification

RemoveComponent

SafeCallException

SetColumns

SetDataSet

SetDataSource

StoreColumns

TDSTableProducer


TDSTableProducer::AcquireLayoutLock

TDSTableProducer	See also

Calls BeginLayout when the HTML table is not currently being laid out.

bool __fastcall AcquireLayoutLock(void);

Description

Applications cannot call this protected method. AcquireLayoutLock is called before recomputing Columns when the fields in the dataset change or when the Columns property changes. AquireLayoutLock returns true if the HTML table is not already being laid out, to indicate that the computation of Columns should proceed. AquireLayoutLock prevents the computation of Columns from looping endlessly in response to the changes that occur during the computation.


TDSTableProducer::BeginLayout

TDSTableProducer	See also

Increments a counter that indicates the number of times the computation of the column order was begun but not completed.

void __fastcall BeginLayout(void);

Description

Applications cannot call this protected method. TDSTableProducer calls BeginLayout internally before making changes to the Columns property or any of the individual THTMLTableColumn objects in Columns. Once the change is complete, TDSTableProducer calls EndLayout.

When all BeginLayout calls have been matched by a corresponding call to EndLayout, the field mapping maintained by DataLink for the fields in the dataset is updated to match both the field bindings of the Columns property and the fields available in the dataset. The Columns property is updated in turn to match the field bindings in DataLink. This ensures that the Columns property matches both the specified column bindings and the fields available in the dataset.


TDSTableProducer::BeginUpdate

TDSTableProducer	See also

Increments a counter that indicates the number of changes to the contents of the HTML table that have been initiated but not completed.

void __fastcall BeginUpdate(void);

Description

Applications should not call BeginUpdate. BeginUpdate is called internally before changes that affect the contents of the HTML table. Once a change is complete, EndUpdate is called. BeginUpdate and EndUpdate allow descendants of TDSTableProducer to wait until changes to the dataset are complete before fetching records for the HTML image of the table.


TDSTableProducer::TDSTableProducer

TDSTableProducer	See also

Creates an instance of TDSTableProducer.

__fastcall virtual TDSTableProducer(Classes::TComponent* AOwner);

Description

Do not instantatiate a TDSTableProducer in an application. Instead, use the new keyword to create the appropriate descendant from within the OnAction event handler of a TWebActionItem that needs to produce an HTML image of a dataset.

After calling the parent object's constructor, TDSTableProducer allocates all the helper objects used by TDSTableProducer and initializes the MaxRows property to 20.


TDSTableProducer::DefineFieldMap

TDSTableProducer	See also

Builds the Fields array in DataLink.

void __fastcall DefineFieldMap(void);

Description

Applications cannot call this protected method. DefineFieldMap rebuilds the field mapping for the dataset that is maintained by DataLink. This mapping reflects both the column bindings of the Columns property and the fields available in the dataset. After calling DefineFieldMap, the Columns property should be updated to match the field bindings in DataLink. This ensures that the Columns property reflects any changes imposed by the dataset.


TDSTableProducer::~TDSTableProducer

TDSTableProducer	See also

Destroys an instance of TDSTableProducer.

__fastcall virtual ~TDSTableProducer(void);

Description

Do not call ~TDSTableProducer directly in an application. Instead, use the delete keyword.

~TDSTableProducer frees all the helper objects used by TDSTableProducer.


TDSTableProducer::DoCreateContent

TDSTableProducer	See also

Indicates whether the Content method should produce a string of HTML commands.

bool __fastcall DoCreateContent(void);

Description

Applications can’t call this protected method. It is called internally by the Content method to allow the OnCreateContent event handler to block the creation of any HTML commands. If DoCreateContent returns true, Content assembles a string of HTML to describe the dataset. If DoCreateContent returns false, Content returns an empty string.

DoCreateContent calls the OnCreateContent event handler if one is assigned. If there is no OnCreateContent event handler, DoCreateContent returns true. Descendants of TDSTableProducer can override DoCreateContent to add additional restrictions on when the HTML describing DataSet should be produced, or to block the OnCreateContent event.


TDSTableProducer::DoFormatCell

TDSTableProducer	See also

Generates an OnFormatCell event.

enum THTMLAlign { haDefault, haLeft, haRight, haCenter };

enum THTMLVAlign { haVDefault, haTop, haMiddle, haBottom, haBaseline };

DYNAMIC void __fastcall DoFormatCell(int CellRow, int CellColumn, System::AnsiString &BgColor, Httpapp::THTMLAlign &Align, Httpapp::THTMLVAlign &VAlign, System::AnsiString &CustomAttrs, System::AnsiString &CellData);

Description

Applications can’t call this protected method. It is called internally by the Content method to allow the OnFormatCell event handler to customize the contents or display attributes of any cell in the HTML table. CellRow and CellColumn indicate the cell about to be rendered as HTML, where CellRow for the table header is 0, and CellColumn for the first column is 0. BgColor, Align, VAlign, and CustomAttrs are the display attributes that can be changed. CellData is the text that goes in the cell.

Descendants of TDSTableProducer can override DoFormatCell to make additional changes to the cells as they are rendered or to block the OnFormatCell event.


TDSTableProducer::DoGetCaption

TDSTableProducer	See also

Generates an OnGetCaption event.

DYNAMIC void __fastcall DoGetCaption(System::AnsiString &TableCaption, THTMLCaptionAlignment &CaptionAlign);

Description

Applications can’t call this protected method. It is called internally by the Content method to let the OnGetTableCaption event handler change the Caption and CaptionAlignment properties when the table caption is rendered as HTML.

Descendants of TDSTableProducer can override DoCreateCaption to make additional changes when the caption is rendered or to block the OnCreateCaption event.


TDSTableProducer::EndLayout

TDSTableProducer	See also

Decrements a counter that indicates the number of times the computation of the column order has been begun but not completed.

void __fastcall EndLayout(void);

Description

Applications can’t call this protected method. TDSTableProducer objects call EndLayout internally after making changes to the Columns property or when changes are made to the fields in DataSet.

Each call to EndLayout should match a corresponding call to BeginLayout. If all BeginLayout calls have been matched by an EndLayout call, EndLayout calls DefineFieldMap to regenerate the field mapping for the dataset maintained by DataLink. The Columns property is then updated to match the field map in DataLink. This ensures that the Columns property matches both the specified column bindings and the fields available in the dataset.


TDSTableProducer::EndUpdate

TDSTableProducer	See also

Decrements a counter that indicates the number of changes to the contents of the HTML table.

void __fastcall EndUpdate(void);

Description

Applications should not call EndUpdate. EndUpdate is called internally after changes to the column bindings or DataSet of the TDSTableProducer. BeginUpdate and EndUpdate allow descendants of TDSTableProducer to wait until changes to the dataset are complete before fetching records for the HTML image of the table.


TDSTableProducer::GetDataSet

TDSTableProducer	See also

Provides the abstract prototype of a method to access the DataSet property.

virtual Db::TDataSet* __fastcall GetDataSet(void) = 0;

Description

Descendants of TDSTableProducer implement the GetDataSet method to access their specific implementation of the DataSet property. Descendants of TDSTableProducer restrict the DataSet property to different classes of TDataSet objects.


TDSTableProducer::GetDataSource

TDSTableProducer	See also

Returns the value of the DataSource property.

Db::TDataSource* __fastcall GetDataSource(void);

Description

GetDataSource is exposed as a protected method so that descendants of TDSTableProducer can override the implementation of the DataSource property.

The DataSource property for TDSTableProducer is an internally generated TDataSource object, not an external component that can be shared with other objects. It is surfaced only for internal APIs that require a TDataSource object rather than working directly with TDataSet.


TDSTableProducer::LayoutChanged

TDSTableProducer	See also

Causes the Columns property to be recomputed when the dataset changes or changes are made to individual column objects.

void __fastcall LayoutChanged(void);

Description

Applications cannot call this protected method. It is called when the Columns property changes or the fields in the dataset change. LayoutChanged recomputes the Columns property after guarding against recursion from the changes to the Columns property that arise in the computation.

LayoutChanged calls AcquireLayoutLock to initiate the changes to Columns. If AcquireLayoutLock does not indicate that the call to LayoutChanged is recursive, LayoutChanged calls EndLayout to perform the actual computation.


TDSTableProducer::LinkActive

TDSTableProducer	See also

Recomputes the Columns property when the dataset becomes active.

void __fastcall LinkActive(bool Value);

Description

Applications cannot call this protected method. LinkActive is called when the DataSource property changes or when the dataset becomes active. It recomputes Columns to reflect any changes that may have occurred in the fields of the dataset when it was not active.


TDSTableProducer::Notification

TDSTableProducer	See also

Adjusts the properties of TDSTableProducer when its helper objects are destroyed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

Notification overrides the inherited method to respond to messages that the DataSource or one of its field objects is about to be destroyed. Notification sets the DataSource property to NULL, or unbinds the column that references the field component.


TDSTableProducer::SetColumns

TDSTableProducer	See also

Sets the Columns property.

void __fastcall SetColumns(THTMLTableColumns* Value);

Description

SetColumns is the protected implementation of the Columns property. SetColumns calls the Assign method of the THTMLTableColumns object stored internally by TDSTableProducer. Thus, the memory for any columns object assigned to the Columns property is never owned or freed by TDSTableProducer.


TDSTableProducer::SetDataSet

TDSTableProducer	See also

Provides the abstract prototype of a method to set the DataSet property.

virtual void __fastcall SetDataSet(Db::TDataSet* ADataSet) = 0;

Description

Descendants of TDSTableProducer override SetDataSet to ensure that the DataSet property can only be set to an appropriate descendant of TDataSet.


TDSTableProducer::SetDataSource

TDSTableProducer	See also

Sets the DataSource property.

void __fastcall SetDataSource(Db::TDataSource* Value);

Description

SetDataSource is the protected implementation of the DataSource property.

The DataSource property for TDSTableProducer is an internally generated TDataSource object, not an external component that can be shared with other objects. It is surfaced only for internal API calls that require a TDataSource object rather than working directly with TDataSet.


TDSTableProducer::StoreColumns

TDSTableProducer	See also

Indicates whether the Columns property is stored when the TDSTableProducer is saved.

bool __fastcall StoreColumns(void);

Description

StoreColumns causes the Columns property to be stored only when the Columns property has a State property of csCustom. The State property for Columns indicates whether the columns represent default display attributes for all the fields in the dataset, or if the display attributes or field bindings of the columns have been customized programmatically or by the Columns editor.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TCustomContentProducer


TDSTableProducerEditor

Hierarchy	Properties	Methods	See also

TDSTableProducer is the base class for the helper object used by TDSTableProducer objects to communicate with a property editor at design time.

Unit

dbweb

Description

Component writers can derive objects from TDSTableProducer to enable new descendants of TDSTableProducer to take advantage of the property editors in the IDE. TDSTableProducerEditor introduces methods to communicate changes between a TDSTableProducer object and the property editor.


TDSTableProducerEditor properties

TDSTableProducerEditor	Alphabetically	Legend

In TDSTableProducerEditor

DataSource

DSTableProducer


TDSTableProducerEditor properties

TDSTableProducerEditor	By object	Legend

DataSource

DSTableProducer


TDSTableProducerEditor::DataSource

TDSTableProducerEditor	See also

Indicates the DataSource property of the associated TDSTableProducer.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Applications should not directly change the DataSource property. DataSource allows the property editor to read or change the internal data source of the TDSTableProducer object.


TDSTableProducerEditor::DSTableProducer

TDSTableProducerEditor	See also

Indicates the TDSTableProducer object that uses TDSTableProducerEditor to communicate with its property editor at design time.

__property TDSTableProducer* DSTableProducer = {read=FDSTableProducer};

Description

Read TDSTableProducer to obtain direct access to the TDSTableProducer object that uses TDSTableProducerEditor.


TDSTableProducerEditor methods

TDSTableProducerEditor	Alphabetically

In TDSTableProducerEditor

~TDSTableProducerEditor

Changed

PostChange

TDSTableProducerEditor

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDSTableProducerEditor methods

TDSTableProducerEditor	By object

~TDSTableProducerEditor

Changed

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

PostChange

SafeCallException

TDSTableProducerEditor


TDSTableProducerEditor::Changed

TDSTableProducerEditor	See also

Provides the interface for a method that responds to change notifications from the TDSTableProducer object.

virtual void __fastcall Changed(void);

Description

The Changed method for TDSTableProducerEditor does nothing. It exists so that descendants of TDSTableProducerEditor can perform any necessary updates when the TDSTableProducer object changes. TDSTableProducer calls Changed when any of its properties change.


TDSTableProducerEditor::TDSTableProducerEditor

TDSTableProducerEditor	See also

Creates an instance of TDSTableProducerEditor.

__fastcall TDSTableProducerEditor(TDSTableProducer* DSTableProducer);

Description

Do not create TDSTableProducerEditor in an application. A TDSTableProducerEditor is created at design time when needed. TDSTableProducerEditor initializes the DSTableProducer property, and sets the Editor property in the TDSTableProducer object passed as the DSTableProducer parameter.


TDSTableProducerEditor::~TDSTableProducerEditor

TDSTableProducerEditor	See also

Destroys an instance of TDSTableProducerEditor.

__fastcall virtual ~TDSTableProducerEditor(void);

Description

Do not call ~TDSTableProducerEditor from an application. A TDSTableProducerEditor object is freed automatically at design time. ~TDSTableProducerEditor sets the Editor property of the associated TDSTableProducer object to NULL.


TDSTableProducerEditor::PostChange

TDSTableProducerEditor	See also

Provides an interface for a method that responds to update notifications from the columns of a TDSTableProducer object.

virtual void __fastcall PostChange(void);

Description

The PostChange method for TDSTableProducerEditor does nothing. It exists so that descendants of TDSTableProducerEditor can perform any necessary updates when the columns of the TDSTableProducer object change. THTMLTableColumns calls PostChange when its columns are changed.


Accessibility

Read-only


Hierarchy

TObject


TDataSetUpdateObject

Hierarchy	Properties	Methods	See also

TDataSetUpdateObject is the abstract base class for update objects used to update otherwise unupdateable queries when cached updates are enabled.

Unit

dbtables

Description

Use TDataSetUpdateObject as a base class when creating customized update objects that can be used to update BDE datasets.  TDataSetUpdateObject declares a single property and some abstract methods, but provides no implementation details: these must be provided by descendant objects.


TDataSetUpdateObject properties

TDataSetUpdateObject	Alphabetically	Legend

In TDataSetUpdateObject

DataSet

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TDataSetUpdateObject properties

TDataSetUpdateObject	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataSet

DesignInfo

Name

Owner

Tag

VCLComObject


TDataSetUpdateObject::DataSet

TDataSetUpdateObject	See also

Dataset is the dataset whose records are updated by the update object.

__property TBDEDataSet* DataSet = {read=GetDataSet, write=SetDataSet};

Description

Descendants of TDataSetUpdateObject must implement the abstract GetDataSet and SetDataSet methods to implement the DataSet property.


TDataSetUpdateObject methods

TDataSetUpdateObject	Alphabetically 	Legend

In TDataSetUpdateObject

~TDataSetUpdateObject

Apply

GetDataSet

SetDataSet

TDataSetUpdateObject

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDataSetUpdateObject methods

TDataSetUpdateObject	By object 	Legend

~TDataSetUpdateObject

Apply

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetDataSet

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

SetDataSet

TDataSetUpdateObject


TDataSetUpdateObject::Apply

TDataSetUpdateObject	See also

Apply applies changes to the dataset specified by the DataSet property.

virtual void __fastcall Apply(Db::TUpdateKind UpdateKind) = 0;

Description

Descendants of TDataSetUpdateObject must implement the abstract Apply method. This method is intended to perform the updates specified by the update object. Descendants must introduce properties to describe the details of the updates that should be performed. The UpdateKind parameter indicates whether the update object should modify existing records, insert new records, or delete existing records.


TDataSetUpdateObject::GetDataSet

TDataSetUpdateObject	See also

GetDataSet returns the value of the DataSet property.

virtual TBDEDataSet* __fastcall GetDataSet(void) = 0;

Description

Override GetDataSet, along with the SetDataSet method, to provide an implementation of the DataSet property. The DataSet property should represent the dataset whose records are updated using the update object.


TDataSetUpdateObject::SetDataSet

 TDataSetUpdateObject	See also

SetDataSet sets the value of the DataSet property.

virtual void __fastcall SetDataSet(TBDEDataSet* ADataSet) = 0;

Description

Override SetDataSet, along with the GetDataSet method, to provide an implementation of the DataSet property. The DataSet property should represent the dataset whose records are updated using the update object.


TDataSetUpdateObject::TDataSetUpdateObject

TDataSetUpdateObject

TDataSetUpdateObject creates a new TDataSetUpdateObject object.

__fastcall virtual TDataSetUpdateObject(Classes::TComponent* AOwner) : Classes::TComponent(AOwner) { }

Description

Call TDataSetUpdateObject to instantiate a TDataSetUpdateObject object.


TDataSetUpdateObject::~TDataSetUpdateObject

TDataSetUpdateObject	See also

~TDataSetUpdateObject frees the memory associated with the TDataSetUpdateObject object.

__fastcall virtual ~TDataSetUpdateObject(void) { }

Description

Do not call ~TDataSetUpdateObject directly. Instead, use the delete keyword on the object, which causes ~TDataSetUpdateObject to be invoked automatically.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent


TDateTimeColors

Hierarchy	Properties	Methods	See also

TDateTimeColors defines a color scheme for TDateTimePicker’s drop-down calendar.

Unit

comctrls

Description

The CalColors property of TDateTimePicker holds a TDateTimeColors object. When TDateTimePicker displays a drop-down calendar illustration (that is, when Kind is dtkDate and DateMode is dmComboBox), the TDateTimeColors determines the calendar’s colors.


TDateTimeColors properties

TDateTimeColors	Alphabetically	Legend

In TDateTimeColors

BackColor

MonthBackColor

TextColor

TitleBackColor

TitleTextColor

TrailingTextColor


TDateTimeColors properties

TDateTimeColors	By object	Legend

BackColor

MonthBackColor

TextColor

TitleBackColor

TitleTextColor

TrailingTextColor


TDateTimeColors::BackColor

TDateTimeColors	See also

The background color displayed between months in the calendar.

__property Graphics::TColor BackColor = {read=FBackColor, write=SetColor, index=0, default=-2147483643};

Description

BackColor may not be implemented in some Windows versions.


TDateTimeColors::MonthBackColor

TDateTimeColors	See also

The background color of the calendar.

__property Graphics::TColor MonthBackColor = {read=FMonthBackColor, write=SetColor, index=4, default=16777215};

Description

MonthBackColor determines the background color of the main section of the calendar, where the dates are displayed.


TDateTimeColors::TextColor

TDateTimeColors	See also

The color of the font used for dates that fall within the displayed month.

__property Graphics::TColor TextColor = {read=FTextColor, write=SetColor, index=1, default=-2147483640};

Description

TextColor determines the color of the numerals for dates that fall within the displayed month. To set the color of dates in the last week of the preceding month and the first week of the the next month, use TrailingTextColor.


TDateTimeColors::TitleBackColor

TDateTimeColors	See also

The background color of the calendar’s title bar.

__property Graphics::TColor TitleBackColor = {read=FTitleBackColor, write=SetColor, index=2, default=-2147483646};

Description

TitleBackColor determines the color of the title bar (above the main section of the calendar), where the month and year are displayed.


TDateTimeColors::TitleTextColor

TDateTimeColors	See also

The color of the font used for the calendar’s title bar.

__property Graphics::TColor TitleTextColor = {read=FTitleTextColor, write=SetColor, index=3, default=16777215};

Description

TitleTextColor determines the color in which the month and year are displayed on the calendar’s title bar.


TDateTimeColors::TrailingTextColor

TDateTimeColors	See also

The color of the font used for dates not in the currently displayed month.

__property Graphics::TColor TrailingTextColor = {read=FTrailingTextColor, write=SetColor, index=5, default=-2147483629};

Description

TrailingTextColor determines the color of the numerals for dates that fall in the last week of the preceding month or the first week of the next month.


TDateTimeColors methods

TDateTimeColors	Alphabetically

In TDateTimeColors

~TDateTimeColors

Assign

TDateTimeColors

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TDateTimeColors methods

TDateTimeColors	By object

~TDateTimeColors

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TDateTimeColors


TDateTimeColors::Assign

TDateTimeColors	See also

Copies the properties from another TDateTimePicker instance.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call the Assign method to duplicate the contents of another TDateTimePicker in a new object.


TDateTimeColors::TDateTimeColors

TDateTimeColors

Creates and initializes a TDateTimeColors instance.

__fastcall TDateTimeColors(TDateTimePicker* AOwner);

Description

TDateTimeColors instantiates a TDateTimeColors object and initializes its properties.


TDateTimeColors::~TDateTimeColors

TDateTimeColors

~TDateTimeColors frees the memory associated with the TDateTimeColors object.

__fastcall virtual ~TDateTimeColors(void) { }

Description

Do not call ~TDateTimeColors directly. Instead, use the delete keyword on the object, which causes ~TDateTimeColors to be invoked automatically.


Scope

Published


Hierarchy

TObject

TPersistent


 TDateTimePicker

Hierarchy	Properties	Methods	Events	See also

TDateTimePicker displays a list box for entering dates or times.

Unit

comctrls

Description

TDateTimePicker is a visual component designed specifically for entering dates or times. In dmComboBox date mode, it resembles a list box or combo box, except that the drop-down list is replaced with a calendar illustration; users can select a date from the calendar. Dates or times can also be selected by scrolling with Up and Down arrows and by typing.


TDateTimePicker properties

TDateTimePicker	Alphabetically	Legend

In TDateTimePicker

CalAlignment

CalColors

Checked

Date

DateFormat

DateMode

DateTime

Kind

MaxDate

MinDate

ParseInput

ShowCheckbox

Time

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ImeMode

ImeName

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TDateTimePicker properties

TDateTimePicker	By object	Legend

Align

BoundsRect

Brush

CalAlignment

CalColors

Checked

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

Date

DateFormat

DateMode

DateTime

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

Kind

Left

MaxDate

MinDate

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

ParentWindow

ParseInput

PopupMenu

ShowCheckbox

ShowHint

Showing

TabOrder

TabStop

Tag

Time

Top

VCLComObject

Visible

Width

WindowProc


TDateTimePicker::CalAlignment

TDateTimePicker	See also

Determines the alignment of the drop-down calendar.

__property TDTCalAlignment CalAlignment = {read=FCalAlignment, write=SetCalAlignment, nodefault};

Description

Set CalAlignment to dtaLeft or dtaRight to align the drop-down calendar on the left or right side of the component. This property is applicable only if Kind = dtkDate and DateMode = dmComboBox, and makes little difference except when the TDateTimePicker component is larger than the drop-down calendar.


TDateTimePicker::CalColors

TDateTimePicker	See also

Determines the colors of the drop-down calendar.

__property TDateTimeColors* CalColors = {read=FCalColors, write=SetCalColors};

Description

The CalColors property points to a TDateTimeColors object that defines colors for the drop-down calendar. The easiest way to select colors for the calendar is to edit CalColors in the Object Inspector. This property is applicable only when Kind = dtkDate and DateMode = dmComboBox.


TDateTimePicker::Checked

TDateTimePicker	See also

Indicates whether the check box next to the date or time is selected.

__property bool Checked = {read=FChecked, write=SetChecked, default=1};

Description

Checked returns true if the check box in the TDateTimePicker component is selected. Setting Checked to true at design time makes the check box appear selected by default.


TDateTimePicker::Date

TDateTimePicker	See also

Indicates the date entered by the user.

__property Controls::TDate Date = {read=GetDate, write=SetDate};

Description

Date represents the date entered by the user. Set Date in program code or in the Obect Inspector to determine which date is selected by default. (Applies only when Kind = dtkDate.)


TDateTimePicker::DateFormat

TDateTimePicker	See also

Specifies format in which the date is presented.

__property TDTDateFormat DateFormat = {read=FDateFormat, write=SetDateFormat, nodefault};

Description

If DateFormat is set to dfShort, the date appears like this: 3/21/97. If DateFormat is set to dfLong, the date appears like this: Friday, March 21, 1997. (Applies only when Kind = dtkDate.)


TDateTimePicker::DateMode

TDateTimePicker	See also

Determines the method of date selection used by the component.

__property TDTDateMode DateMode = {read=FDateMode, write=SetDateMode, nodefault};

Description

If DateMode is dmComboBox, the component has a drop-down calendar illustration from which the user can select a date. If DateMode is dmUpDown, the component has Up/Down arrows with which the user can adjust the date. (Applies only when Kind = dtkDate.)


TDateTimePicker::DateTime

TDateTimePicker	See also

Indicates the date and time.

__property System::TDateTime DateTime = {read=FDateTime, write=SetDateTime};

Description

DateTime represents both a date and a time. If the Kind property is switched at runtime, TDateTimePicker continues to track both the last date entered and the last time entered. If the Kind property never changes, DateTime can be set programmatically (for example, by reading system date and time information) to indicate both a date and a time.


TDateTimePicker::Kind

TDateTimePicker	See also

Determines whether the component is a date selector or a time selector.

__property TDateTimeKind Kind = {read=FKind, write=SetKind, nodefault};

Description

If Kind is dtkDate, the component is used to select a date. If Kind is dtkTime, the component is used to select a time.


TDateTimePicker::MaxDate

TDateTimePicker	See also

Determines the latest allowable date that can be entered.

__property Controls::TDate MaxDate = {read=FMaxDate, write=SetMaxDate};

Description

Assign a value to MaxDate to limit the range of dates that the user can enter. Out-of-range dates raise the EDateTimeError exception. (Applies only when Kind = dtkDate.)


TDateTimePicker::MinDate

TDateTimePicker	See also

Determines the earliest allowable date that can be entered.

__property Controls::TDate MinDate = {read=FMinDate, write=SetMinDate};

Description

Assign a value to MinDate to limit the range of dates that the user can enter. Out-of-range dates raise the EDateTimeError exception. (Applies only when Kind = dtkDate.)


TDateTimePicker::ParseInput

TDateTimePicker	See also

Enables the OnUserInput event.

__property bool ParseInput = {read=FParseInput, write=SetParseInput, nodefault};

Description

If ParseInput is true, the OnUserInput event occurs whenever the user types into the component’s edit box.


TDateTimePicker::ShowCheckbox

TDateTimePicker	See also

Displays a check box next to the date or time.

__property bool ShowCheckbox = {read=FShowCheckbox, write=SetShowCheckbox, default=0};

Description

Set ShowCheckbox to true to display a check box in the TDateTimePicker component.


TDateTimePicker::Time

TDateTimePicker	See also

Indicates the time entered by the user.

__property Controls::TTime Time = {read=GetTime, write=SetTime};

Description

Time represents the time entered by the user. Set Time in program code or in the Obect Inspector to determine which time is selected by default. (Applies only when Kind = dtkTime.)


TDateTimePicker events

TDateTimePicker	Alphabetically	Legend

In TDateTimePicker

OnChange

OnCloseUp

OnDropDown

OnUserInput

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TDateTimePicker events

TDateTimePicker	By object	Legend

OnChange

OnClick

OnCloseUp

OnDblClick

OnDragDrop

OnDragOver

OnDropDown

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnStartDrag

OnUserInput


TDateTimePicker::OnChange

TDateTimePicker

Occurs when a date or time is entered.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action whenever the date or time entered in the component changes.


TDateTimePicker::OnCloseUp

TDateTimePicker	See also

Occurs when the drop-down calendar closes.

__property Classes::TNotifyEvent OnCloseUp = {read=FOnCloseUp, write=FOnCloseUp};

Description

Write an OnCloseUp event handler to implement special processing that needs to occur only when the drop-down calendar closes.


TDateTimePicker::OnDropDown

TDateTimePicker	See also

Occurs when the user opens the drop-down calendar by clicking the arrow at the right of the control.

__property Classes::TNotifyEvent OnDropDown = {read=FOnDropDown, write=FOnDropDown};

Description

Write an OnDropDown event handler to implement special processing that needs to occur only when the drop-down calendar is opened.


TDateTimePicker::OnUserInput

TDateTimePicker	See also

Occurs when the user types directly into the component’s edit box.

__property TDTParseInputEvent OnUserInput = {read=FOnUserInput, write=FOnUserInput};

Description

This event occurs only if ParseInput is set to true. Write an OnUserInput event handler implement special processing that needs to occur when the user types directly into the TDateTimePicker (rather than selecting with the drop-down calendar or scroll arrows). UserString is the string that the user types, and DateAndTime represents the value of the Date or Time property.


TDateTimePicker methods

TDateTimePicker	Alphabetically

In TDateTimePicker

~TDateTimePicker

TDateTimePicker

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TDateTimePicker methods

TDateTimePicker	By object

~TDateTimePicker

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TDateTimePicker

Update

UpdateControlState


TDateTimePicker::TDateTimePicker

TDateTimePicker	See also

Creates and initializes a TDateTimePicker instance.

__fastcall virtual TDateTimePicker(Classes::TComponent* AOwner);

Description

TDateTimePicker calls the parent object's constructor method and initializes the Date and Time properties to the current date and time. It also sets the following ControlStyle flags: csCaptureMouse, csOpaque, csClickEvents, csDoubleClicks, and csFixedHeight.


TDateTimePicker::~TDateTimePicker

TDateTimePicker	See also

Destroys the TDateTimePicker instance and frees its memory.

__fastcall virtual ~TDateTimePicker(void);

Description

Do not call ~TDateTimePicker directly in an application. Instead, use the delete keyword on the object, which causes ~TDateTimePicker to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


EAbort

Hierarchy	Properties	Methods	See also

EAbort is the exception class for errors that should not display an error message dialog box.

Unit

sysutils

Description

Call EAbort to throw an exception without displaying an error message in a dialog box. If applications do not trap such “silent” exceptions, the EAbort exception is passed to TApplication::HandleException.

The easiest way to throw an EAbort exception is to call the Abort procedure.


EAbort properties

EAbort	Alphabetically

Derived from Exception

HelpContext

Message


EAbort properties

EAbort	By object

HelpContext

Message


EAbort methods

EAbort	Alphabetically

In EAbort

~EAbort

EAbort

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAbort methods

EAbort	By object

~EAbort

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EAbort

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAbort::EAbort

EAbort	See also

EAbort creates a new EAbort object.

__fastcall EAbort(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EAbort(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EAbort(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EAbort(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EAbort(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EAbort(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EAbort(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EAbort(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

EAbort instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EAbort("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EAbort::~EAbort

EAbort	See also

~EAbort frees the memory associated with the EAbort object.

__fastcall virtual ~EAbort(void) { }

Description

Do not call ~EAbort directly. Instead, use the delete keyword on the object, which causes ~EAbort to be invoked automatically.


Hierarchy

TObject

Exception


EAbort example

EAbort


EAbstractError

Hierarchy	Properties	Methods

EAbstractError is the exception class for attempts to call an abstract method.

Unit

sysutils

Description

EAbstractError is thrown when an application tries to call an abstract method. It is also thrown at design time when a component with an abstract method is placed on a form.

Abstract methods are declared with the abstract directive and must be overriden in descendent classes before an instance object can be created.


EAbstractError properties

EAbstractError	Alphabetically

Derived from Exception

HelpContext

Message


EAbstractError properties

EAbstractError	By object

HelpContext

Message


EAbstractError methods

EAbstractError	Alphabetically

In EAbstractError

~EAbstractError

EAbstractError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAbstractError methods

EAbstractError	By object

~EAbstractError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EAbstractError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAbstractError::EAbstractError

EAbstractError	See also

EAbstractError creates a new EAbstractError object.

__fastcall EAbstractError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EAbstractError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EAbstractError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EAbstractError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EAbstractError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EAbstractError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EAbstractError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EAbstractError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext){ }

Description

EAbstractError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EAbstractError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EAbstractError::~EAbstractError

EAbstractError	See also

~EAbstractError frees the memory associated with the EAbstractError object.

__fastcall virtual ~EAbstractError(void) { }

Description

Do not call ~EAbstractError directly. Instead, use the delete keyword on the object, which causes ~EAbstractError to be invoked automatically.


Hierarchy

TObject

Exception


EAbstractError example

EAbstractError


EAccessViolation

Hierarchy	Properties	Methods	See also

EAccessViolation is the exception class for invalid memory access errors.

Unit

sysutils

Description

EAccessViolation is thrown when an application

•	Dereferences a NULL pointer.

•	Writes to a code page.

•	Attempts to access a memory address for which there is no virtual memory allocated to the application.

As a descendant of EExternal, EAccessViolation saves the Windows exception record (if there is one) in its ExceptionRecord data structure.

Note

Applications should not throw EAccessViolation directly, but should instead rely on the runtime to throw this exception.


EAccessViolation properties

EAccessViolation	Alphabetically

Derived from Exception

HelpContext

Message


EAccessViolation properties

EAccessViolation	By object

HelpContext

Message


EAccessViolation methods

EAccessViolation	Alphabetically

In EAccessViolation

~EAccessViolation

EAccessViolation

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAccessViolation methods

EAccessViolation	By object

~EAccessViolation

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EAccessViolation

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAccessViolation::EAccessViolation

EAccessViolation	See also

EAccessViolation creates a new EAccessViolation object.

__fastcall EAccessViolation(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EAccessViolation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EAccessViolation(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EAccessViolation(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EAccessViolation(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EAccessViolation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EAccessViolation(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EAccessViolation(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EAccessViolation instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EAccessViolation("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EAccessViolation::~EAccessViolation

EAccessViolation 	See also

~EAccessViolation frees the memory associated with the EAccessViolation object.

__fastcall virtual ~EAccessViolation(void) { }

Description

Do not call ~EAccessViolation directly. Instead, use the delete keyword on the object, which causes ~EAccessViolation to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EAccessViolation example

EAccessViolation


EAssertionFailed

Hierarchy	Properties	Methods

EAssertionFailed is the exception class for Assert procedures performed on Boolean expressions that return false.

Unit

sysutils

Description

EAssertionFailed is thrown by the Assert procedure when an assertion fails in the VCL or in other Object Pascal source.


EAssertionFailed properties

EAssertionFailed	Alphabetically

Derived from Exception

HelpContext

Message


EAssertionFailed properties

EAssertionFailed	By object

HelpContext

Message


EAssertionFailed methods

EAssertionFailed	Alphabetically

In EAssertionFailed

~EAssertionFailed

EAssertionFailed

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Destroy

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAssertionFailed methods

EAssertionFailed	By object

~EAssertionFailed

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Destroy

Dispatch

EAssertionFailed

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EAssertionFailed::EAssertionFailed

EAssertionFailed

EAssertionFailed creates a new EAssertionFailed object.

__fastcall EAssertionFailed(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EAssertionFailed(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EAssertionFailed(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EAssertionFailed(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EAssertionFailed(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EAssertionFailed(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EAssertionFailed(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EAssertionFailed(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EAssertionFailed instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EAssertionError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EAssertionFailed::~EAssertionFailed

EAssertionFailed

~EAssertionFailed frees the memory associated with the EAssertionFailed object.

__fastcall virtual ~EAssertionFailed(void) { }

Description

Do not call ~EAssertionFailed directly. Instead, use the delete keyword on the object, which causes ~EAssertionFailed to be invoked automatically.


Hierarchy

TObject

Exception


EAssertionFailed example

EAssertionFailed


EBitsError

Hierarchy	Properties	Methods	See also

EBitsError is the exception class for invalid attempts to access an array of Boolean values.

Unit

classes

Description

EBitsError is thrown when an application attempts to access a Boolean array (an instance of the TBits class) using an index value that is too large or too small. This can occur when the value of the Index parameter of the Bits property is

•	Less than zero.

•	Equal to or greater than the Size property.


EBitsError properties

EBitsError	Alphabetically

Derived from Exception

HelpContext

Message


EBitsError properties

EBitsError	By object

HelpContext

Message


EBitsError methods

EBitsError	Alphabetically

In EBitsError

~EBitsError

EBitsError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EBitsError methods

EBitsError	By object

~EBitsError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EBitsError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EBitsError::EBitsError

EBitsError	See also

EBitsError creates a new EBitsError object.

__fastcall EBitsError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EBitsError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EBitsError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EBitsError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EBitsError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EBitsError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EBitsError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EBitsError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EBitsError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EBitsError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EBitsError::~EBitsError

EBitsError

~EBitsError frees the memory associated with the EBitsError object.

__fastcall virtual ~EBitsError(void) { }

Description

Do not call ~EBitsError directly. Instead, use the delete keyword on the object, which causes ~EBitsError to be invoked automatically.


Hierarchy

TObject

Exception


EClassNotFound

Hierarchy	Properties	Methods	See also

EClassNotFound is the exception class for the failure to find a specified component when reading from a stream.

Unit

classes

Description

EClassNotFound is thrown if a class name that has not been linked into the current application is encountered when reading a component from a stream. This can happen when a component exists on a form, but has been removed from the type declaration.


EClassNotFound properties

EClassNotFound	Alphabetically

Derived from Exception

HelpContext

Message


EClassNotFound properties

EClassNotFound	By object

HelpContext

Message


EClassNotFound methods

EClassNotFound	Alphabetically

In EClassNotFound

~EClassNotFound

EClassNotFound

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Destroy

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EClassNotFound methods

EClassNotFound	By object

~EClassNotFound

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Destroy

Dispatch

EClassNotFound

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EClassNotFound::EClassNotFound

EClassNotFound	See also

EClassNotFound creates a new EClassNotFound object.

__fastcall EClassNotFound(const System::AnsiString Msg) : Classes::EFilerError(Msg) { }

__fastcall EClassNotFound(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Msg, Args, Args_Size) { }

__fastcall EClassNotFound(int Ident, Extended Dummy) : Classes::EFilerError(Ident, Dummy) { }

__fastcall EClassNotFound(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Ident, Args, Args_Size) { }

__fastcall EClassNotFound(const System::AnsiString Msg, int AHelpContext) : Classes::EFilerError(Msg, AHelpContext) { }

__fastcall EClassNotFound(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EClassNotFound(int Ident, int AHelpContext) : Classes::EFilerError(Ident, AHelpContext) { }

__fastcall EClassNotFound(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Ident, Args, Args_Size, AHelpContext) { }

Description

EClassNotFound instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EClassNotFound("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EClassNotFound::~EClassNotFound

EClassNotFound

~EClassNotFound frees the memory associated with the EClassNotFound object.

__fastcall virtual ~EClassNotFound(void) { }

Description

Do not call ~EClassNotFound directly. Instead, use the delete keyword on the object, which causes ~EClassNotFound to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError

EFilerError


EClassNotFound example

EClassNotFound


EConvertError

Hierarchy	Properties	Methods	See also

EConvertError is the exception class for string and object conversion errors.

Unit

sysutils

Description

EConvertError is thrown when

•	An application makes an unsuccessful attempt to convert an integer, float, date, or time to a string, or to convert a string to one of these other types.

•	An application passes an invalid argument to a formatting routine.

•	An application attempts to assign one type of component derived from TPersistent to another component derived from TPersistent when such an assignment is not possible. For example, EConvertError is thrown by the attempted assignment of a TButton control to a TEdit control.


EConvertError properties

EConvertError	Alphabetically

Derived from Exception

HelpContext

Message


EConvertError properties

EConvertError	By object

HelpContext

Message


EConvertError methods

EConvertError	Alphabetically

In EConvertError

~EConvertError

EConvertError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EConvertError methods

EConvertError	By object

~EConvertError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EConvertError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EConvertError::EConvertError

EConvertError	See also

EConvertError creates a new EConvertError object.

__fastcall EConvertError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EConvertError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EConvertError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EConvertError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EConvertError(const System::AnsiString Msg, int AHelpContext): Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EConvertError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EConvertError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EConvertError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext){ }

Description

EConvertError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EConvertError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EConvertError::~EConvertError

EConvertError	See also

~EConvertError frees the memory associated with the EConvertError object.

__fastcall virtual ~EConvertError(void) { }

Description

Do not call ~EConvertError directly. Instead, use the delete keyword on the object, which causes ~EConvertError to be invoked automatically.


Hierarchy

TObject

Exception


EComponentError

Hierarchy	Properties	Methods	See also

EComponentError is the exception class for registering and renaming components.

Unit

classes

Description

EComponentError is thrown when:

•	C++Builder cannot register a component.

•	An application cannot rename a component.

•	A request is made to retrieve the COM interface of a component that doesn’t support COM.

To register a component, write a procedure called “Register” in the namespace of the component’s source file. This procedure must call RegisterComponents for each component you want to register.

Failure to rename a component occurs when an application tries to rename the component at runtime, and the new name is the same as the name of another component or is not a valid C++ identifier.


EComponentError properties

EComponentError	Alphabetically

Derived from Exception

HelpContext

Message


EComponentError properties

EComponentError	By object

HelpContext

Message


EComponentError methods

EComponentError	Alphabetically

In EComponentError

~EComponentError

EComponentError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EComponentError methods

EComponentError	By object

~EComponentError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EComponentError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EComponentError::EComponentError

EComponentError	See also

EComponentError creates a new EComponentError object.

__fastcall EComponentError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EComponentError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EComponentError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EComponentError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EComponentError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EComponentError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EComponentError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EComponentError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EComponentError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EComponentError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EComponentError::~EComponentError

EComponentError

~EComponentError frees the memory associated with the EComponentError object.

__fastcall virtual ~EComponentError(void) { }

Description

Do not call ~EComponentError directly. Instead, use the delete keyword on the object, which causes ~EComponentError to be invoked automatically.


Hierarchy

TObject

Exception


EControlC

Hierarchy	Properties	Methods	See also

EControlC is the exception class for Ctrl+C key presses in console applications.

Unit

sysutils

Description

EControlC is raised when a user presses Ctrl+C to terminate a console application.

As a descendant of EExternal, EControlC saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EControlC properties

EControlC	Alphabetically

Derived from Exception

HelpContext

Message


EControlC properties

EControlC	By object

HelpContext

Message


EControlC methods

EControlC	Alphabetically

In EControlC

~EControlC

EControlC

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EControlC methods

EControlC	By object

~EControlC

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EControlC

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EControlC::EControlC

EControlC	See also

EControlC creates a new EControlC object.

__fastcall EControlC(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EControlC(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EControlC(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EControlC(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EControlC(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EControlC(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EControlC(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EControlC(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EControlC instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EControlC("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EControlC::~EControlC

EControlC	See also

~EControlC frees the memory associated with the EControlC object.

__fastcall virtual ~EControlC(void) { }

Description

Do not call ~EControlC directly. Instead, use the delete keyword on the object, which causes ~EControlC to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EControlC example

EControlC


EDatabaseError

Hierarchy	Properties	Methods	See also

EDatabaseError is the exception class for database errors.

Unit

db

Description

EDatabaseError is thrown when a component detects a database error. Use EDatabaseError in an exception handling block or to create a database exception.


EDatabaseError properties

EDatabaseError	Alphabetically

Derived from Exception

HelpContext

Message


EDatabaseError properties

EDatabaseError	By object

HelpContext

Message


EDatabaseError methods

EDatabaseError	Alphabetically

In EDatabaseError

~EDatabaseError

EDatabaseError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDatabaseError methods

EDatabaseError	By object

~EDatabaseError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDatabaseError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDatabaseError::EDatabaseError

EDatabaseError	See also

EDatabaseError creates a new EDatabaseError object.

__fastcall EDatabaseError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EDatabaseError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EDatabaseError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EDatabaseError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EDatabaseError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EDatabaseError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDatabaseError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EDatabaseError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext)

Description

EDatabaseError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDatabaseError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EDatabaseError::~EDatabaseError

EDatabaseError

~EDatabaseError frees the memory associated with the EDatabaseError object.

__fastcall virtual ~EDatabaseError(void) { }

Description

Do not call ~EDatabaseError directly. Instead, use the delete keyword on the object, which causes ~EDatabaseError to be invoked automatically.


Hierarchy

TObject

Exception


EDatabaseError example

EDatabaseError


EDBClient

Hierarchy	Properties	Methods	See also

EDBClient is the exception class for client dataset errrors.

Unit

dbclient

Description

EDBClient is thrown if an error occurs when an application is using a TClientDataSet object.


EDBClient properties

EDBClient	Alphabetically	Legend

In EDBClient

ErrorCode

Derived from Exception

HelpContext

Message


EDBClient properties

EDBClient	By object	Legend

ErrorCode

HelpContext

Message


EDBClient::ErrorCode

EDBClient	See also

The error code returned by the BDE.

__property Word ErrorCode = {read=FErrorCode, nodefault};

Description

ErrorCode is the error code returned by the BDE.

DBIResult is a special integer type used to represent error codes returned by the Borland Database Engine (BDE).


EDBClient methods

EDBClient	Alphabetically

In EDBClient

~EDBClient

EDBClient

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDBClient methods

EDBClient	By object

~EDBClient

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDBClient

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDBClient::EDBClient

EDBClient	See also

Initializes an instance of EDBClient using error information returned by the BDE.

__fastcall EDBClient(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Msg, Args, Args_Size) { }

__fastcall EDBClient(int Ident, Extended Dummy) : Db::EDatabaseError(Ident, Dummy) { }

__fastcall EDBClient(int Ident, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Ident, Args, Args_Size) { }

__fastcall EDBClient(const System::AnsiString Msg, int AHelpContext) : Db::EDatabaseError(Msg, AHelpContext) { }

__fastcall EDBClient(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDBClient(int Ident, int AHelpContext) : Db::EDatabaseError(Ident, AHelpContext) { }

__fastcall EDBClient(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Ident, Args, Args_Size, AHelpContext) { }

Description

EDBClient instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDBClient("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EDBClient::~EDBClient

EDBClient	See also

~EDBClient frees the memory associated with the EDBClient object.

__fastcall virtual ~EDBClient(void) { }

Description

Do not call ~EDBClient directly. Instead, use the delete keyword on the object, which causes ~EDBClient to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

Exception

EDatabaseError


EDBEditError

Hierarchy	Properties	Methods	See also

EDBEditError is the exception class for data that are incompatible with a specified mask.

Unit

mask

Description

EDBEditError is thrown when an application attempts to use data that are incompatible with the mask specified for a field.

A mask restricts the data that can be put into an edit box or data field. Use the EditMask property to specify a mask.


EDBEditError properties

EDBEditError	Alphabetically

Derived from Exception

HelpContext

Message


EDBEditError properties

EDBEditError	By object

Message

HelpContext


EDBEditError methods

EDBEditError	Alphabetically

In EDBEditError

~EDBEditError

EDBEditError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDBEditError methods

EDBEditError	By object

~EDBEditError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDBEditError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDBEditError::EDBEditError

EDBEditError	See also

EDBEditError creates a new EDBEditError object.

__fastcall EDBEditError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EDBEditError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EDBEditError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EDBEditError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EDBEditError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EDBEditError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDBEditError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EDBEditError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EDBEditError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDBEditError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EDBEditError::~EDBEditError

EDBEditError

~EDBEditError frees the memory associated with the EDBEditError object.

__fastcall virtual ~EDBEditError(void) { }

Description

Do not call ~EDBEditError directly. Instead, use the delete keyword on the object, which causes ~EDBEditError to be invoked automatically.


Hierarchy

TObject

Exception


EDBEngineError

Hierarchy	Properties	Methods	See also

EDBEngineError is the exception class for Borland Database Engine errors.

Unit

dbtables

Description

EDBEngineError is thrown whenever a BDE error occurs. Its Errors property contains TDBError objects.

When EDBEngineError exceptions are thrown at design time, they appear in a special dialog (TDbEngineErrorDlg) that displays the complete stack of BDE errors. At runtime, unhandled EDBEngineError exceptions generate the same message box as other exceptions.


EDBEngineError properties

EDBEngineError	Alphabetically	Legend

In EDBEngineError

ErrorCount

Errors

Derived from Exception

HelpContext

Message


EDBEngineError properties

EDBEngineError	By object	Legend

ErrorCount

Errors

HelpContext

Message


EDBEngineError::ErrorCount

EDBEngineError 	See also

Indicates the total number of errors contained in the Errors property.

__property int ErrorCount = {read=GetErrorCount, nodefault};

Description

Use ErrorCount as an upper bound when iterating through the errors in the error stack.


EDBEngineError::Errors

EDBEngineError	See also

Lists the entire Borland Database Engine error stack.

__property TDBError* Errors[int Index] = {read=GetError};

Description

Errors is an index of TDBError objects. The first error has an index value of 0.


EDBEngineError methods

EDBEngineError	Alphabetically

In EDBEngineError

~EDBEngineError

EDBEngineError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDBEngineError methods

EDBEngineError	By object

~EDBEngineError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDBEngineError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDBEngineError::EDBEngineError

EDBEngineError	See also

Creates an instance of EDBEngineError using a specified BDE error code.

__fastcall EDBEngineError(Word ErrorCode);

__fastcall EDBEngineError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Msg, Args, Args_Size) { }

__fastcall EDBEngineError(int Ident, Extended Dummy) : Db::EDatabaseError(Ident, Dummy) { }

__fastcall EDBEngineError(int Ident, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Ident, Args, Args_Size) { }

__fastcall EDBEngineError(const System::AnsiString Msg, int AHelpContext) : Db::EDatabaseError(Msg, AHelpContext) { }

__fastcall EDBEngineError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDBEngineError(int Ident, int AHelpContext) : Db::EDatabaseError(Ident, AHelpContext) { }

__fastcall EDBEngineError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Ident, Args, Args_Size, AHelpContext) { }

Description

EDBEngineError calls the constructor inherited from Exception (using an empty string) to construct an initialized instance of EDBEngineError. It then creates a TDBError instance for each error in the BDE error stack and builds a single string containing all the error messages. If the BDE is uninitialized when EDBEngineError is called, the method generates only one generic error message and one TDBError instance.

Word is a BDE error code.

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EDBEngineError::~EDBEngineError

EDBEngineError	See also

Disposes of the EDBEngineError instance and each TDBError instance.

__fastcall virtual ~EDBEngineError(void);

Description

~EDBEngineError first disposes of each TDBError instance referenced in the Errors property, then calls the inherited desctructor to dispose of the EDBEngineError instance itself.


Accessibility

Read-only


Hierarchy

TObject

Exception

EDatabaseError


 TEdit

Hierarchy	Properties	Methods	Events	See also

TEdit is a wrapper for a Windows single-line edit control.

Unit

stdctrls

Description

Use a TEdit object to put a standard Windows edit control on a form. Edit controls are used to retrieve text that users type. Edit controls can also display text to the user.

When only displaying text to the user, choose an edit control to allow users to select text and copy it to the Clipboard. Choose a label object if the selection capabilities of an edit control are not needed.

TEdit implements the generic behavior introduced in TCustomEdit. TEdit publishes many of the properties inherited from TCustomEdit, but does not introduce any new behavior. For specialized edit controls, use other descendant classes of TCustomEdit or derive from it.


TEdit properties

TEdit	Alphabetically	Legend

Derived from TCustomEdit

AutoSelect

AutoSize

BorderStyle

CanUndo

CharCase

HideSelection

MaxLength

Modified

OEMConvert

PasswordChar

ReadOnly

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TEdit properties

TEdit	By object	Legend

Align

AutoSelect

AutoSize

BorderStyle

BoundsRect

Brush

CanUndo

CharCase

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

HideSelection

Hint

ImeMode

ImeName

Left

MaxLength

Modified

Name

OEMConvert

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PasswordChar

PopupMenu

ReadOnly

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TEdit events

TEdit	Alphabetically	Legend

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TEdit events

TEdit	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TEdit methods

TEdit	Alphabetically

In TEdit

~TEdit

TEdit

Derived from TCustomEdit

Clear

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TEdit methods

TEdit	By object

~TEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TEdit

Undo

Update

UpdateControlState


TEdit::TEdit

TEdit

Creates a new TEdit object.

__fastcall virtual TEdit(Classes::TComponent* AOwner) : Stdctrls::TCustomEdit(AOwner) { }

__fastcall TEdit(HWND ParentWindow) : Stdctrls::TCustomEdit(ParentWindow) { }

Description

Do not call TEdit directly when creating an edit control at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TEdit object. Edit controls placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TEdit object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the edit control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TEdit::~TEdit

TEdit

Frees the memory associated with the TEdit object.

__fastcall virtual ~TEdit(void) { }

Description

Do not call ~TEdit directly. Instead, use the delete keyword on the object, which causes ~TEdit to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit


EDivByZero

Hierarchy	Properties	Methods	See also

EDivByZero is the exception class for integer divide-by-zero errors.

Unit

sysutils

Description

EDivByZero is thrown when an application tries to divide an integer by zero. In practice, this error is easy to trap and correct in a try..except block.

As a descendant of EExternal, EDivByZero saves the Windows exception record (if there is one) in its ExceptionRecord data structure.

Note

Floating-point divide-by-zero errors throw the EZeroDivide exception.


EDivByZero properties

EDivByZero	Alphabetically

Derived from Exception

HelpContext

Message


EDivByZero properties

EDivByZero	By object

HelpContext

Message


EDivByZero methods

EDivByZero	Alphabetically

In EDivByZero

~EDivByZero

EDivByZero

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDivByZero methods

EDivByZero	By object

~EDivByZero

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDivByZero

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDivByZero::EDivByZero

EDivByZero	See also

EDivByZero creates a new EDivByZero object.

__fastcall EDivByZero(const System::AnsiString Msg) : Sysutils::EIntError(Msg) { }

__fastcall EDivByZero(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EIntError(Msg, Args, Args_Size) { }

__fastcall EDivByZero(int Ident, Extended Dummy) : Sysutils::EIntError(Ident, Dummy) { }

__fastcall EDivByZero(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EIntError(Ident, Args, Args_Size) { }

__fastcall EDivByZero(const System::AnsiString Msg, int AHelpContext) : Sysutils::EIntError(Msg, AHelpContext) { }

__fastcall EDivByZero(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EIntError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDivByZero(int Ident, int AHelpContext) : Sysutils::EIntError(Ident, AHelpContext) { }

__fastcall EDivByZero(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EIntError(Ident, Args, Args_Size, AHelpContext) { }

Description

EDivByZero instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDivByZero("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EDivByZero::~EDivByZero

EDivByZero	See also

~EDivByZero frees the memory associated with the EDivByZero object.

__fastcall virtual ~EDivByZero(void) { }

Description

Do not call ~EDivByZero directly. Instead, use the delete keyword on the object, which causes ~EDivByZero to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EIntError


EDivByZero example

EDivByZero


EDateTimeError

Hierarchy	Properties	Methods	See also

EDateTimeError is the exception class for invalid date and time entries.

Unit

comctrls

Description

EDateTimeError is raised by TDateTimePicker when an invalid date or time is entered.


EDateTimeError properties

EDateTimeError	Alphabetically

Derived from Exception

HelpContext

Message


EDateTimeError properties

EDateTimeError	By object

HelpContext

Message


EDateTimeError methods

EDateTimeError	Alphabetically

In EDateTimeError

~EDateTimeError

EDateTimeError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDateTimeError methods

EDateTimeError	By object

~EDateTimeError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EDateTimeError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EDateTimeError::EDateTimeError

EDateTimeError	See also

EDateTimeError creates a new EDateTimeError object.

__fastcall EDateTimeError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EDateTimeError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EDateTimeError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EDateTimeError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EDateTimeError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EDateTimeError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EDateTimeError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EDateTimeError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext){ }

Description

EDateTimeError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EDateTimeError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EDateTimeError::~EDateTimeError

EDateTimeError	See also

~EDateTimeError frees the memory associated with the EDateTimeError object.

__fastcall virtual ~EDateTimeError(void) { }

Description

Do not call ~EDateTimeError directly. Instead, use the delete keyword on the object, which causes ~EDateTimeError to be invoked automatically.


Hierarchy

TObject

Exception


EDateTimeError example

EDateTimeError


EExternalException

Hierarchy	Properties	Methods	See also

EExternalException is the exception class for invalid exception codes.

Unit

sysutils

Description

EExternalException is thrown when C++Builder detects an unrecognized exception code. C++Builder recognizes the following exception codes:

•	STATUS_INTEGER_DIVIDE_BY_ZERO

•	STATUS_ARRAY_BOUNDS_EXCEEDED

•	STATUS_FLOAT_OVERFLOW

•	STATUS_FLOAT_INEXACT_RESULT

•	STATUS_FLOAT_INVALID_OPERATION

•	STATUS_FLOAT_STACK_CHECK

•	STATUS_FLOAT_DIVIDE_BY_ZERO

•	STATUS_INTEGER_OVERFLOW

•	STATUS_FLOAT_UNDERFLOW

•	STATUS_FLOAT_DENORMAL_OPERAND

•	STATUS_ACCESS_VIOLATION

•	STATUS_PRIVILEGED_INSTRUCTION

•	STATUS_CONTROL_C_EXIT

•	STATUS_STACK_OVERFLOW

Any exception code that is not on the list above throws an EExternalException.

As a descendant of EExternal, EExternalException saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EExternalException properties

EExternalException	Alphabetically

Derived from Exception

HelpContext

Message


EExternalException properties

EExternalException	By object

HelpContext

Message


EExternalException methods

EExternalException	Alphabetically

In EExternalException

~EExternalException

EExternalException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EExternalException methods

EExternalException	By object

~EExternalException

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EExternalException

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EExternalException::EExternalException

EExternalException	See also

EExternalException creates a new EExternalException object.

__fastcall EExternalException(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EExternalException(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EExternalException(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EExternalException(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EExternalException(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EExternalException(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EExternalException(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EExternalException(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EExternalException instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EExternalException("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EExternalException::~EExternalException

EExternalException

~EExternalException frees the memory associated with the EExternalException object.

__fastcall virtual ~EExternalException(void) { }

Description

Do not call ~EExternalException directly. Instead, use the delete keyword on the object, which causes ~EExternalException to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EExternal

Hierarchy	Properties	Methods	See also

EExternal is the exception class that captures Windows exception records.

Unit

sysutils

Description

EExternal is the ancestor of all exception classes that can represent Win32 exception codes. EExternal has a public data structure, ExceptionRecord:

_EXCEPTION_RECORD *ExceptionRecord;

typedef struct _EXCEPTION_RECORD {

    DWORD    ExceptionCode;

    DWORD ExceptionFlags;

    struct _EXCEPTION_RECORD *ExceptionRecord;

    PVOID ExceptionAddress;

    DWORD NumberParameters;

    DWORD ExceptionInformation[EXCEPTION_MAXIMUM_PARAMETERS];

    } EXCEPTION_RECORD;

The fields in ExceptionRecord correspond to the Windows EXCEPTION_RECORD structure. When the exception is not thrown originally by the operating system, ExceptionRecord is empty.


EExternal properties

EExternal	Alphabetically

Derived from Exception

HelpContext

Message


EExternal properties

EExternal	By object

HelpContext

Message


EExternal methods

EExternal	Alphabetically

In EExternal

~EExternal

EExternal

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EExternal methods

EExternal	By object

~EExternal

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EExternal

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EExternal::EExternal

EExternal	See also

EExternal creates a new EExternal object.

__fastcall EExternal(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EExternal(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EExternal(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EExternal(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EExternal(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EExternal(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EExternal(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EExternal(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EExternal instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EExternal("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EExternal::~EExternal

EExternal

~EExternal frees the memory associated with the EExternal object.

__fastcall virtual ~EExternal(void) { }

Description

Do not call ~EExternal directly. Instead, use the delete keyword on the object, which causes ~EExternal to be invoked automatically.


Hierarchy

TObject

Exception


EFCreateError

Hierarchy	Properties	Methods	See also

EFCreateError is the exception class for streaming file-creation errors.

Unit

classes

Description

EFCreateError is thrown when an application unsuccessfully attempts to create a file. This can occur, for example, if a user specifies an invalid file name, or specifies the name of an existing file that cannot be overwritten because the user lacks appropriate access permission.


EFCreateError properties

EFCreateError	Alphabetically

Derived from Exception

HelpContext

Message


EFCreateError properties

EFCreateError	By object

HelpContext

Message


EFCreateError methods

EFCreateError	Alphabetically

In EFCreateError

~EFCreateError

EFCreateError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EFCreateError methods

EFCreateError	By object

~EFCreateError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EFCreateError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EFCreateError::EFCreateError

EFCreateError	See also

EFCreateError creates a new EFCreateError object.

__fastcall EFCreateError(const System::AnsiString Msg) : Classes::EStreamError(Msg) { }

__fastcall EFCreateError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EStreamError(Msg, Args, Args_Size) { }

__fastcall EFCreateError(int Ident, Extended Dummy) : Classes::EStreamError(Ident, Dummy) { }

__fastcall EFCreateError(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EStreamError(Ident, Args, Args_Size) { }

__fastcall EFCreateError(const System::AnsiString Msg, int AHelpContext) : Classes::EStreamError(Msg, AHelpContext) { }

__fastcall EFCreateError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EStreamError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EFCreateError(int Ident, int AHelpContext) : Classes::EStreamError(Ident, AHelpContext) { }

__fastcall EFCreateError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EStreamError(Ident, Args, Args_Size, AHelpContext) { }

Description

EFCreateError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EFCreateError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EFCreateError::~EFCreateError

EFCreateError

~EFCreateError frees the memory associated with the EFCreateError object.

__fastcall virtual ~EFCreateError(void) { }

Description

Do not call ~EFCreateError directly. Instead, use the delete keyword on the object, which causes ~EFCreateError to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError


EFilerError

Hierarchy	Properties	Methods	See also

EFilerError is the exception class for file stream errors.

Unit

classes

Description

EFilerError is thrown when an attempt is made to register the same class twice.

EFilerError is also the immediate ancestor of the following exceptions that occur when reading or writing streams:

Exception	Description

EReadError	Cannot read the specified number of bytes

EWriteError	Cannot write the specified number of bytes

EClassNotFound	Component is not linked to application

EInvalidImage	Cannot read a resource file

EMethodNotFound	Cannot find the implementation of a method


EFilerError properties

EFilerError	Alphabetically

Derived from Exception

HelpContext

Message


EFilerError properties

EFilerError	By object

HelpContext

Message


EFilerError methods

EFilerError	Alphabetically

In EFilerError

~EFilerError

EFilerError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EFilerError methods

EFilerError	By object

~EFilerError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EFilerError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EFilerError::EFilerError

EFilerError	See also

EFilerError creates a new EFilerError object.

__fastcall EFilerError(const System::AnsiString Msg) : Classes::EStreamError(Msg) { }

__fastcall EFilerError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EStreamError(Msg, Args, Args_Size) { }

__fastcall EFilerError(int Ident, Extended Dummy) : Classes::EStreamError(Ident, Dummy) { }

__fastcall EFilerError(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EStreamError(Ident, Args, Args_Size) { }

__fastcall EFilerError(const System::AnsiString Msg, int AHelpContext) : Classes::EStreamError(Msg, AHelpContext) { }

__fastcall EFilerError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EStreamError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EFilerError(int Ident, int AHelpContext) : Classes::EStreamError(Ident, AHelpContext) { }

__fastcall EFilerError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EStreamError(Ident, Args, Args_Size, AHelpContext) { }

Description

EFilerError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EFilerError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EFilerError::~EFilerError

EFilerError

~EFilerError frees the memory associated with the EFilerError object.

__fastcall virtual ~EFilerError(void) { }

Description

Do not call ~EFilerError directly. Instead, use the delete keyword on the object, which causes ~EFilerError to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError


EFOpenError

Hierarchy	Properties	Methods	See also

EFOpenError is the exception class for file-opening errors during streaming.

Unit

classes

Description

EFOpenError is thrown when an application cannot open a specified file. This can occur, for example, because the file doesn’t exist or is not in the directory where the application is searching for it.


EFOpenError properties

EFOpenError	Alphabetically

Derived from Exception

HelpContext

Message


EFOpenError properties

EFOpenError	By object

HelpContext

Message


EFOpenError methods

EFOpenError	Alphabetically

In EFOpenError

~EFOpenError

EFOpenError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EFOpenError methods

EFOpenError	By object

~EFOpenError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EFOpenError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EFOpenError::EFOpenError

EFOpenError	See also

EFOpenError creates a new EFOpenError object.

__fastcall EFOpenError(const System::AnsiString Msg) : Classes::EStreamError(Msg) { }

__fastcall EFOpenError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EStreamError(Msg, Args, Args_Size) { }

__fastcall EFOpenError(int Ident, Extended Dummy) : Classes::EStreamError(Ident, Dummy) { }

__fastcall EFOpenError(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EStreamError(Ident, Args, Args_Size) { }

__fastcall EFOpenError(const System::AnsiString Msg, int AHelpContext) : Classes::EStreamError(Msg, AHelpContext) { }

__fastcall EFOpenError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EStreamError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EFOpenError(int Ident, int AHelpContext) : Classes::EStreamError(Ident, AHelpContext) { }

__fastcall EFOpenError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EStreamError(Ident, Args, Args_Size, AHelpContext) { }

Description

EFOpenError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EFOpenError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EFOpenError::~EFOpenError

EFOpenError

~EFOpenError frees the memory associated with the EFOpenError object.

__fastcall virtual ~EFOpenError(void) { }

Description

Do not call ~EFOpenError directly. Instead, use the delete keyword on the object, which causes ~EFOpenError to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError


EIntfCastError

Hierarchy	Properties	Methods	See also

EIntfCastError is the exception class for interface casting errors.

Unit

sysutils

Description

EIntfCastError is thrown in the VCL when an illegal typecast is attempted on an interface.


EIntfCastError properties

EIntfCastError	Alphabetically

Derived from Exception

HelpContext

Message


EIntfCastError properties

EIntfCastError	By object

HelpContext

Message


EIntfCastError methods

EIntfCastError	Alphabetically

In EIntfCastError

~EIntfCastError

EIntfCastError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EIntfCastError methods

EIntfCastError	By object

~EIntfCastError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EIntfCastError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EIntfCastError::EIntfCastError

EIntfCastError	See also

EIntfCastError creates a new EIntfCastError object.

__fastcall EIntfCastError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EIntfCastError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EIntfCastError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EIntfCastError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EIntfCastError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EIntfCastError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EIntfCastError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EIntfCastError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EIntfCastError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EIntfCastError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EIntfCastError::~EIntfCastError

EIntfCastError

~EIntfCastError frees the memory associated with the EIntfCastError object.

__fastcall virtual ~EIntfCastError(void) { }

Description

Do not call ~EIntfCastError directly. Instead, use the delete keyword on the object, which causes ~EIntfCastError to be invoked automatically.


Hierarchy

TObject

Exception


EInOutError

Hierarchy	Properties	Methods	See also

EInOutError is the exception class for file input/output errors.

Unit

sysutils

Description

EInOutError is thrown when an operating-system file input/output error occurs, provided I/O checking is enabled. (To enable or disable I/O checking, choose Project|Options and select the Pascal tab.) The resulting error code is returned in the local ErrorCode variable, which can take the following values.

Error code	Meaning

2	File not found.

3	Invalid file name.

4	Too many open files.

5	Access denied.

100	EOF.

101	Disk full.

106	Invalid input.

Note

If an I/O error occurs when I/O checking is disabled, the application must call the IOResult function to clear the error.


EInOutError properties

EInOutError	Alphabetically

Derived from Exception

HelpContext

Message


EInOutError properties

EInOutError	By object

HelpContext

Message


EInOutError methods

EInOutError	Alphabetically

In EInOutError

~EInOutError

EInOutError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInOutError methods

EInOutError	By object

~EInOutError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInOutError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInOutError::EInOutError

EInOutError	See also

EInOutError creates a new EInOutError object.

__fastcall EInOutError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInOutError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInOutError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInOutError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EInOutError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInOutError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInOutError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInOutError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInOutError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInOutError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInOutError::~EInOutError

EInOutError

~EInOutError frees the memory associated with the EInOutError object.

__fastcall virtual ~EInOutError(void) { }

Description

Do not call ~EInOutError directly. Instead, use the delete keyword on the object, which causes ~EInOutError to be invoked automatically.


Hierarchy

TObject

Exception


EInOutError example

EInOutError


EIntError

Hierarchy	Properties	Methods	See also

EIntError is the base class for integer math error exceptions.

Unit

sysutils

Description

EIntError is a generic integer math exception. Although it is never thrown in the runtime library, it is the base from which other integer math exceptions descend. These are the integer math exceptions:

Exception	Meaning

EDivByZero	An attempt was made to divide by zero

ERangeError	Number or expression out of range

EIntOverflow	Integer operation overflowed

As descendants of EExternal, these classes save the Windows exception record (if there is one) in their ExceptionRecord data structure.


EIntError properties

EIntError	Alphabetically

Derived from Exception

HelpContext

Message


EIntError properties

EIntError	By object

HelpContext

Message


EIntError methods

EIntError	Alphabetically

In EIntError

~EIntError

EIntError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EIntError methods

EIntError	By object

~EIntError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EIntError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EIntError::EIntError

EIntError	See also

EIntError creates a new EIntError object.

__fastcall EIntError(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EIntError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EIntError(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EIntError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EIntError(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EIntError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EIntError(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EIntError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EIntError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EIntError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EIntError::~EIntError

EIntError

~EIntError frees the memory associated with the EIntError object.

__fastcall virtual ~EIntError(void) { }

Description

Do not call ~EIntError directly. Instead, use the delete keyword on the object, which causes ~EIntError to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EIntError example

EIntError


EIntOverflow

Hierarchy	Properties	Methods	See also

EIntOverflow is the exception class for integer calculations whose results are too large to fit in the allocated register.

Unit

sysutils

Description

EIntOverflow is an integer math exception that occurs when a calculated result is too large to fit in the register allocated for it and data is therefore lost. Overflow is determined by the size of the machine register.

Floating-point register overflows throw the EOverflow exception.

As a descendant of EExternal, EIntOverflow saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EIntOverflow properties

EIntOverflow	Alphabetically

Derived from Exception

HelpContext

Message


EIntOverflow properties

EIntOverflow	By object

HelpContext

Message


EIntOverflow methods

EIntOverflow	Alphabetically

In EIntOverflow

~EIntOverflow

EIntOverflow

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EIntOverflow methods

EIntOverflow	By object

~EIntOverflow

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EIntOverflow

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EIntOverflow::EIntOverflow

EIntOverflow	See also

EIntOverflow creates a new EIntOverflow object.

__fastcall EIntOverflow(const System::AnsiString Msg) : Sysutils::EIntError(Msg) { }

__fastcall EIntOverflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EIntError(Msg, Args, Args_Size) { }

__fastcall EIntOverflow(int Ident, Extended Dummy) : Sysutils::EIntError(Ident, Dummy) { }

__fastcall EIntOverflow(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EIntError(Ident, Args, Args_Size) { }

__fastcall EIntOverflow(const System::AnsiString Msg, int AHelpContext) : Sysutils::EIntError(Msg, AHelpContext) { }

__fastcall EIntOverflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EIntError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EIntOverflow(int Ident, int AHelpContext) : Sysutils::EIntError(Ident, AHelpContext) { }

__fastcall EIntOverflow(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EIntError(Ident, Args, Args_Size, AHelpContext) { }

Description

EIntOverflow instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EIntOverflow("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EIntOverflow::~EIntOverflow

EIntOverflow

~EIntOverflow frees the memory associated with the EIntOverflow object.

__fastcall virtual ~EIntOverflow(void) { }

Description

Do not call ~EIntOverflow directly. Instead, use the delete keyword on the object, which causes ~EIntOverflow to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EIntError


EIntOverflow example

EIntOverflow


EInvalidOp

Hierarchy	Properties	Methods	See also

EInvalidOp is the exception class for undefined floating-point operations.

Unit

sysutils

Description

EInvalidOp is thrown when the processor encounters an undefined instruction, invalid operation, or floating-point processor stack overflow.

As a descendant of EExternal, EInvalidOp saves the Windows exception record (if there is one) in its ExceptionRecord data structure.

Note:	Do not confuse this object with EInvalidOperation.


EInvalidOp properties

EInvalidOp	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidOp properties

EInvalidOp	By object

HelpContext

Message


EInvalidOp methods

EInvalidOp	Alphabetically

In EInvalidOp

~EInvalidOp

EInvalidOp

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidOp methods

EInvalidOp	By object

~EInvalidOp

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidOp

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidOp::EInvalidOp

EInvalidOp	See also

EInvalidOp creates a new EInvalidOp object.

__fastcall EInvalidOp(const System::AnsiString Msg) : Sysutils::EMathError(Msg) { }

__fastcall EInvalidOp(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Msg, Args, Args_Size) { }

__fastcall EInvalidOp(int Ident, Extended Dummy) : Sysutils::EMathError(Ident, Dummy) { }

__fastcall EInvalidOp(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Ident, Args, Args_Size) { }

__fastcall EInvalidOp(const System::AnsiString Msg, int AHelpContext) : Sysutils::EMathError(Msg, AHelpContext) { }

__fastcall EInvalidOp(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidOp(int Ident, int AHelpContext) : Sysutils::EMathError(Ident, AHelpContext) { }

__fastcall EInvalidOp(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidOp instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidOp("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidOp::~EInvalidOp

EInvalidOp

~EInvalidOp frees the memory associated with the EInvalidOp object.

__fastcall virtual ~EInvalidOp(void) { }

Description

Do not call ~EInvalidOp directly. Instead, use the delete keyword on the object, which causes ~EInvalidOp to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EMathError


EInvalidCast

Hierarchy	Properties	Methods	See also

EInvalidCast is an exception class for typecasting errors.

Unit

sysutils

EInvalidCast is thrown in the VCL when an illegal typecast is attempted.


EInvalidCast properties

EInvalidCast	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidCast properties

EInvalidCast	By object

HelpContext

Message


EInvalidCast methods

EInvalidCast	Alphabetically

In EInvalidCast

~EInvalidCast

EInvalidCast

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidCast methods

EInvalidCast	By object

~EInvalidCast

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidCast

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidCast::EInvalidCast

EInvalidCast	See also

EInvalidCast creates a new EInvalidCast object.

__fastcall EInvalidCast(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInvalidCast(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInvalidCast(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInvalidCast(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EInvalidCast(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInvalidCast(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidCast(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInvalidCast(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidCast instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidCast("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidCast::~EInvalidCast

EInvalidCast

~EInvalidCast frees the memory associated with the EInvalidCast object.

__fastcall virtual ~EInvalidCast(void) { }

Description

Do not call ~EInvalidCast directly. Instead, use the delete keyword on the object, which causes ~EInvalidCast to be invoked automatically.


Hierarchy

TObject

Exception


EInvalidGridOperation

Hierarchy	Properties	Methods	See also

EInvalidGridOperation is the exception class for illegal grid operations.

Unit

grids

Description

EInvalidGridOperation is thrown when an application attempts an illegal operation on a grid. For example, EInvalidGridOperation is thrown if an application tries to access a cell or column that does not exist within the grid.


EInvalidGridOperation properties

EInvalidGridOperation	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidGridOperation properties

EInvalidGridOperation	By object

Message

HelpContext


EInvalidGridOperation methods

EInvalidGridOperation	Alphabetically

In EInvalidGridOperation

~EInvalidGridOperation

EInvalidGridOperation

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidGridOperation methods

EInvalidGridOperation	By object

~EInvalidGridOperation

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidGridOperation

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidGridOperation::EInvalidGridOperation

EInvalidGridOperation	See also

EInvalidGridOperation creates a new EInvalidGridOperation object.

__fastcall EInvalidGridOperation(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInvalidGridOperation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInvalidGridOperation(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInvalidGridOperation(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EInvalidGridOperation(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInvalidGridOperation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidGridOperation(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInvalidGridOperation(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidGridOperation instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidGridOperation("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidGridOperation::~EInvalidGridOperation

EInvalidGridOperation

~EInvalidGridOperation frees the memory associated with the EInvalidGridOperation object.

__fastcall virtual ~EInvalidGridOperation(void) { }

Description

Do not call ~EInvalidGridOperation directly. Instead, use the delete keyword on the object, which causes ~EInvalidGridOperation to be invoked automatically.


Hierarchy

TObject

Exception


EInvalidGridOperation example

EInvalidGridOperation


EInvalidGraphicOperation

Hierarchy	Properties	Methods	See also

EInvalidGraphicOperation is the exception class for illegal operations on graphics.

Unit

graphics

Description

EInvalidGraphicOperation is thrown when an illegal operation is attempted on a graphic. For example, an EInvalidGraphicOperation exception is raised when an application attempts to resize an icon or copy an icon to the Clipboard.


EInvalidGraphicOperation properties

EInvalidGraphicOperation	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidGraphicOperation properties

EInvalidGraphicOperation	By object

HelpContext

Message


EInvalidGraphicOperation methods

EInvalidGraphicOperation	Alphabetically

In EInvalidGraphicOperation

~EInvalidGraphicOperation

EInvalidGraphicOperation

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidGraphicOperation methods

EInvalidGraphicOperation	By object

~EInvalidGraphicOperation

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidGraphicOperation

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidGraphicOperation::EInvalidGraphicOperation

EInvalidGraphicOperation	See also

EInvalidGraphicOperation creates a new EInvalidGraphicOperation object.

__fastcall EInvalidGraphicOperation(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInvalidGraphicOperation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInvalidGraphicOperation(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInvalidGraphicOperation(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EInvalidGraphicOperation(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInvalidGraphicOperation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidGraphicOperation(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInvalidGraphicOperation(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidGraphicOperation instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidGraphicOperation("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidGraphicOperation::~EInvalidGraphicOperation

EInvalidGraphicOperation

~EInvalidGraphicOperation frees the memory associated with the EInvalidGraphicOperation object.

__fastcall virtual ~EInvalidGraphicOperation(void) { }

Description

Do not call ~EInvalidGraphicOperation directly. Instead, use the delete keyword on the object, which causes ~EInvalidGraphicOperation to be invoked automatically.


Hierarchy

TObject

Exception


EInvalidGraphic

Hierarchy	Properties	Methods

EInvalidGraphic is the exception class for unrecognized graphic files.

Unit

graphics

Description

EInvalidGraphic is thrown when

•	An application attempts to load a file that is not a valid bitmap, icon, metafile, or user-defined graphic type into a picture.

•	An application attempts to load a file with an unrecognized extension.

•	An image does not match the format specified in a call to LoadFromClipboardFormat or SaveToClipboardFormat.


EInvalidGraphic properties

EInvalidGraphic	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidGraphic properties

EInvalidGraphic	By object

HelpContext

Message


EInvalidGraphic methods

EInvalidGraphic	Alphabetically

In EInvalidGraphic

~EInvalidGraphic

EInvalidGraphic

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidGraphic methods

EInvalidGraphic	By object

~EInvalidGraphic

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidGraphic

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidGraphic::EInvalidGraphic

EInvalidGraphic	See also

EInvalidGraphic creates a new EInvalidGraphic object.

__fastcall EInvalidGraphic(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInvalidGraphic(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInvalidGraphic(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInvalidGraphic(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EInvalidGraphic(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInvalidGraphic(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidGraphic(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInvalidGraphic(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidGraphic instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidGraphic("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidGraphic::~EInvalidGraphic

EInvalidGraphic

~EInvalidGraphic frees the memory associated with the EInvalidGraphic object.

__fastcall virtual ~EInvalidGraphic(void) { }

Description

Do not call ~EInvalidGraphic directly. Instead, use the delete keyword on the object, which causes ~EInvalidGraphic to be invoked automatically.


Hierarchy

TObject

Exception


EInvalidArgument

Hierarchy	Properties	Methods	See also

EInvalidArgument is the exception class for out-of-range parameters in specialized math and accounting functions.

Unit

math

Description

EInvalidArgument is thrown by some functions in the Math unit (mostly financial functions) when one of the parameters is out of range or makes the calculation impossible.

As a descendant of EExternal, EInvalidArgument saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EInvalidArgument properties

EInvalidArgument	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidArgument properties

EInvalidArgument	By object

HelpContext

Message


EInvalidArgument methods

EInvalidArgument	Alphabetically

In EInvalidArgument

~EInvalidArgument

EInvalidArgument

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidArgument methods

EInvalidArgument	By object

~EInvalidArgument

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidArgument

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidArgument::EInvalidArgument

EInvalidArgument	See also

EInvalidArgument creates a new EInvalidArgument object.

__fastcall EInvalidArgument(const System::AnsiString Msg) : Sysutils::EMathError(Msg) { }

__fastcall EInvalidArgument(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Msg, Args, Args_Size) { }

__fastcall EInvalidArgument(int Ident, Extended Dummy) : Sysutils::EMathError(Ident, Dummy) { }

__fastcall EInvalidArgument(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Ident, Args, Args_Size) { }

__fastcall EInvalidArgument(const System::AnsiString Msg, int AHelpContext) : Sysutils::EMathError(Msg, AHelpContext) { }

__fastcall EInvalidArgument(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidArgument(int Ident, int AHelpContext) : Sysutils:: EMathError(Ident, AHelpContext) { }

__fastcall EInvalidArgument(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Ident, Args, Args_Size, AHelpContextS) { }

Description

EInvalidArgument instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidArgument("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidArgument::~EInvalidArgument

EInvalidArgument

~EInvalidArgument frees the memory associated with the EInvalidArgument object.

__fastcall virtual ~EInvalidArgument(void) { }

Description

Do not call ~EInvalidArgument directly. Instead, use the delete keyword on the object, which causes ~EInvalidArgument to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EMathError


EInvalidArgument example

EInvalidArgument


EInvalidImage

Hierarchy	Properties	Methods	See also

EInvalidImage is the exception class for unsuccessful attempts to read resource files.

Unit

classes

Description

EInvalidImage is thrown when an application cannot read a resource file. This occurs most often because the specified file is not a resource file.

This error can occur if the TStream object’s read and write methods are used inconsistently. Always use ReadComponentRes to read components written with WriteComponentRes, and ReadComponent to read components written with WriteComponent. Failure to use the corresponding read and write methods can result in EInvalidImage exceptions.


EInvalidImage properties

EInvalidImage	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidImage properties

EInvalidImage	By object

HelpContext

Message


EInvalidImage methods

EInvalidImage	Alphabetically

In EInvalidImage

~EInvalidImage

EInvalidImage

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidImage methods

EInvalidImage	By object

~EInvalidImage

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidImage

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidImage::EInvalidImage

EInvalidImage	See also

EInvalidImage creates a new EInvalidImage object.

__fastcall EInvalidImage(const System::AnsiString Msg) : Classes::EFilerError(Msg) { }

__fastcall EInvalidImage(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Msg, Args, Args_Size) { }

__fastcall EInvalidImage(int Ident, Extended Dummy) : Classes::EFilerError(Ident, Dummy) { }

__fastcall EInvalidImage(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Ident, Args, Args_Size) { }

__fastcall EInvalidImage(const System::AnsiString Msg, int AHelpContext) : Classes::EFilerError(Msg, AHelpContext) { }

__fastcall EInvalidImage(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidImage(int Ident, int AHelpContext) : Classes::EFilerError(Ident, AHelpContext) { }

__fastcall EInvalidImage(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidImage instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidImage("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidImage::~EInvalidImage

EInvalidImage

~EInvalidImage frees the memory associated with the EInvalidImage object

__fastcall virtual ~EInvalidImage(void) { }

Description

Do not call ~EInvalidImage directly. Instead, use the delete keyword on the object, which causes ~EInvalidImage to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError

EFilerError


EInvalidImage example

EInvalidImage


EInvalidOperation

Hierarchy	Properties	Methods	See also

EInvalidOperation is the exception class for invalid operations on a component.

Unit

classes

Description

EInvalidOperation is thrown when an application attempts an operation that requires a window handle on a component that does not have a parent (Parent = NULL). This exception can also occur if a drag-and-drop operation is attempted from a form (for example, Form1::BeginDrag).

Note:	Do not confuse this object with EInvalidOp.


EInvalidOperation properties

EInvalidOperation	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidOperation properties

EInvalidOperation	By object

HelpContext

Message


EInvalidOperation methods

EInvalidOperation	Alphabetically

In EInvalidOperation

~EInvalidOperation

EInvalidOperation

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidOperation methods

EInvalidOperation	By object

~EInvalidOperation

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidOperation

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidOperation::EInvalidOperation

EInvalidOperation	See also

EInvalidOperation creates a new EInvalidOperation object.

__fastcall EInvalidOperation(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInvalidOperation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInvalidOperation(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInvalidOperation(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }__fastcall EInvalidOperation(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInvalidOperation(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidOperation(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInvalidOperation(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidOperation instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidOperation("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidOperation::~EInvalidOperation

EInvalidOperation

~EInvalidOperation frees the memory associated with the EInvalidOperation object.

__fastcall virtual ~EInvalidOperation(void) { }

Description

Do not call ~EInvalidOperation directly. Instead, use the delete keyword on the object, which causes ~EInvalidOperation to be invoked automatically.


Hierarchy

TObject

Exception


EInvalidPointer

Hierarchy	Properties	Methods

EInvalidPointer is the exception class for invalid pointer operations.

Unit

sysutils

Description

EInvalidPointer is thrown when an application attempts an invalid pointer operation. For example, it can occur if an application tries to dispose of the same pointer twice, or refers to a pointer which has already been disposed of.


EInvalidPointer properties

EInvalidPointer	Alphabetically

Derived from Exception

HelpContext

Message


EInvalidPointer properties

EInvalidPointer	By object

HelpContext

Message


EInvalidPointer methods

EInvalidPointer	Alphabetically

In EInvalidPointer

~EInvalidPointer

EInvalidPointer

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidPointer methods

EInvalidPointer	By object

~EInvalidPointer

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EInvalidPointer

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EInvalidPointer::EInvalidPointer

EInvalidPointer	See also

EInvalidPointer creates a new EInvalidPointer object.

__fastcall EInvalidPointer(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EInvalidPointer(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EInvalidPointer(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EInvalidPointer(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EInvalidPointer(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EInvalidPointer(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EInvalidPointer(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EInvalidPointer(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EInvalidPointer instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EInvalidPointer("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EInvalidPointer::~EInvalidPointer

EInvalidPointer

~EInvalidPointer frees the memory associated with the EInvalidPointer object.

__fastcall virtual ~EInvalidPointer(void) { }

Description

Do not call ~EInvalidPointer directly. Instead, use the delete keyword on the object, which causes ~EInvalidPointer to be invoked automatically.


Hierarchy

TObject

Exception


EInvalidPointer example

EInvalidPointer


EListError

Hierarchy	Properties	Methods	See also

EListError is the exception class for list and string errors.

Unit

classes

Description

EListError is thrown when an error is made in a list, TStrings, or TStringList object. This exception commonly occurs when an application refers to an item that is out of the list’s range.

EListError also occurs if an application tries to add a duplicate string to a TStringList object when the value of the Duplicates property is dupError.

An EListError exception is thrown when an application attempts to insert a string into a sorted string list, since the insertion of a string at a specified position may put the list out of order.


EListError properties

EListError	Alphabetically

Derived from Exception

HelpContext

Message


EListError properties

EListError	By object

HelpContext

Message


EListError methods

EListError	Alphabetically

In EListError

~EListError

EListError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EListError methods

EListError	By object

~EListError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EListError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EListError::EListError

EListError	See also

EListError creates a new EListError object.

__fastcall EListError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EListError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EListError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EListError(int Ident, const System::TVarRec * Args, const int

Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EListError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EListError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EListError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EListError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EListError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EListError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EListError::~EListError

EListError

~EListError frees the memory associated with the EListError object.

__fastcall virtual ~EListError(void) { }

Description

Do not call ~EListError directly. Instead, use the delete keyword on the object, which causes ~EListError to be invoked automatically.


Hierarchy

TObject

Exception


EListError example

EListError


EMathError

Hierarchy	Properties	Methods	See also

EMathError is the exception class for floating-point math errors.

Unit

sysutils

Description

EMathError is the base class from which all specific floating-point math exceptions descend. EMathError itself is never thrown in the VCL.

The following exceptions descend from EMathError:

Exception	Meaning

EInvalidArgument	Parameter out of range

EInvalidOp	Processor encountered an undefined instruction

EOverflow	Floating-point operation overflowed

EUnderflow	Floating-point operation underflowed

EZeroDivide	Attempt to divide by zero

As descendants of EExternal, these classes save the Windows exception record (if there is one) in their ExceptionRecord data structure.


EMathError properties

EMathError	Alphabetically

Derived from Exception

HelpContext

Message


EMathError properties

EMathError	By object

HelpContext

Message


EMathError methods

EMathError	Alphabetically

In EMathError

~EMathError

EMathError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EMathError methods

EMathError	By object

~EMathError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EMathError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EMathError::EMathError

EMathError	See also

EMathError creates a new EMathError object.

__fastcall EMathError(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EMathError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EMathError(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EMathError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EMathError(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EMathError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EMathError(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EMathError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EMathError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EMathError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EMathError::~EMathError

EMathError

~EMathError frees the memory associated with the EMathError object.

__fastcall virtual ~EMathError(void) { }

Description

Do not call ~EMathError directly. Instead, use the delete keyword on the object, which causes ~EMathError to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EMathError example

EMathError


EMCIDeviceError

Hierarchy	Properties	Methods	See also

EMCIDeviceError is the exception class for devices that provide a Media Control Interface (MCI) driver.

Unit

mplayer

Description

EMCIDeviceError is thrown if an error occurs when accessing a multimedia device. The most common cause for the exception is trying to access a multimedia device before it has been opened with the TMediaPlayer::Open method.


EMCIDeviceError properties

EMCIDeviceError	Alphabetically

Derived from Exception

HelpContext

Message


EMCIDeviceError properties

EMCIDeviceError	By object

Message

HelpContext


EMCIDeviceError methods

EMCIDeviceError	Alphabetically

In EMCIDeviceError

~EMCIDeviceError

EMCIDeviceError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EMCIDeviceError methods

EMCIDeviceError	By object

~EMCIDeviceError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EMCIDeviceError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EMCIDeviceError::EMCIDeviceError

EMCIDeviceError

EMCIDeviceError creates a new EMCIDeviceError object.

__fastcall EMCIDeviceError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EMCIDeviceError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EMCIDeviceError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EMCIDeviceError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EMCIDeviceError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EMCIDeviceError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EMCIDeviceError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EMCIDeviceError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EMCIDeviceError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EMCIDeviceError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EMCIDeviceError::~EMCIDeviceError

EMCIDeviceError

~EMCIDeviceError frees the memory associated with the EMCIDeviceError object.

__fastcall virtual ~EMCIDeviceError(void) { }

Description

Do not call ~EMCIDeviceError directly. Instead, use the delete keyword on the object, which causes ~EMCIDeviceError to be invoked automatically.


Hierarchy

TObject

Exception


EMCIDeviceError example

EMCIDeviceError


EMenuError

Hierarchy	Properties	Methods	See also

EMenuError is the exception class for errors involving menu items.

Unit

menus

Description

EMenuError is thrown if an error occurs while an application is working with menu items. For example, an EMenuError exception occurs if an application attempts to delete a menu item that doesn’t exist.


EMenuError properties

EMenuError	Alphabetically

Derived from Exception

HelpContext

Message


EMenuError properties

EMenuError	By object

Message

HelpContext


EMenuError methods

EMenuError	Alphabetically

In EMenuError

~EMenuError

EMenuError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EMenuError methods

EMenuError	By object

~EMenuError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EMenuError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EMenuError::EMenuError

EMenuError	See also

EMenuError creates a new EMenuError object.

__fastcall EMenuError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EMenuError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EMenuError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EMenuError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EMenuError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EMenuError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EMenuError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EMenuError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EMenuError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EMenuError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EMenuError::~EMenuError

EMenuError

~EMenuError frees the memory associated with the EMenuError object.

__fastcall virtual ~EMenuError(void) { }

Description

Do not call ~EMenuError directly. Instead, use the delete keyword on the object, which causes ~EMenuError to be invoked automatically.


Hierarchy

TObject

Exception


EMenuError example

EMenuError


TEnumPropDesc

Hierarchy	Methods	See also

TEnumPropDesc provides the mapping between strings used to name the values of a property in an OLE control object and the values themselves.

Unit

olectrls

Description

Use TEnumPropDesc to interpret the strings used by an OLE control object to represent the values of one of its properties.  TEnumPropDesc can provide a list of possible value strings to a callback function, or map between the string names of property values and the values themselves.  TEnumPropDesc objects are made available through the GetEnumPropDesc method of an OLE control object.


TEnumPropDesc methods

TEnumPropDesc	Alphabetically

In TEnumPropDesc

~TEnumPropDesc

GetStrings

StringToValue

TEnumPropDesc

ValueToString

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TEnumPropDesc methods

TEnumPropDesc	By object

~TEnumPropDesc

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetStrings

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

StringToValue

TEnumPropDesc

ValueToString


TEnumPropDesc::TEnumPropDesc

TEnumPropDesc	See also

Creates an instance of TEnumPropDesc.

__fastcall TEnumPropDesc(int DispID, int ValueCount, const _di_ITypeInfo TypeInfo);

Description

TEnumPropDesc is called indirectly by an OLE control object to create an instance of TEnumPropDesc to represent the values of one of its properties.  Applications should not need to create instances of TEnumPropDesc.  When working with OLE properties, get the TEnumPropDesc objects from the OLE control object.

DispID identifies the property of the OLE object. ValueCount is the number of distinct values the property can take. TypeInfo is an ITypeInfo object that the constructor can use to capture the values and their strings.


TEnumPropDesc::~TEnumPropDesc

TEnumPropDesc	See also

Destroys an instance of TEnumPropDesc.

__fastcall virtual ~TEnumPropDesc(void);

Description

Do not call ~TEnumPropDesc directly in an application.  Instead, an application should call delete, which causes the TOleControl object that owns the TEnumPropDesc object to destroy it automatically.

~TEnumPropDesc frees the internal list used to map value strings to property values.


TEnumPropDesc::GetStrings

TEnumPropDesc	See also

Calls the callback Proc for each property value string.

void __fastcall GetStrings(Classes::TGetStrProc &Proc);

Description

Use GetStrings to execute code for every property value string represented in the TEnumPropDesc object.  The callback Proc is called for every value, with the S parameter set to a string that gives the integer value followed by the string representation of that value.

For example, consider a  TEnumPropDesc object that represents a color property, with values equal to TColor values. The callback Proc would be called for every built-in color name with strings of the form ‘255 - clRed’.


TEnumPropDesc::StringToValue

TEnumPropDesc	See also

Maps a string representation of the property value to the integer value.

int __fastcall StringToValue(const System::AnsiString S);

Description

Use StringToValue to map the string representation of a property value used by an OLE control object to an integer value that is a more accurate representation of the property value.  If the property value is not an integer, the integer associated with the string can be a pointer to the value.


TEnumPropDesc::ValueToString

TEnumPropDesc	See also

Maps an integer that indicates the value of the property to the string representation of that value used by the OLE control object.

System::AnsiString __fastcall ValueToString(int V);

Description

Use ValueToString to map the integer value of a property value to the string representation used by an OLE control object.  If the property value is not an integer, the integer associated with the string can be a pointer to the value.


Hierarchy

TObject


ENoResultSet

Hierarchy	Properties	Methods	See also

ENoResultSet is the exception class for unsuccessful attempts to open a dataset query.

Unit

dbtables

Description

ENoResultSet is thrown by TQuery when an attempt is made to open the query without a SELECT statement.


ENoResultSet properties

ENoResultSet	Alphabetically

Derived from Exception

HelpContext

Message


ENoResultSet properties

ENoResultSet	By object

HelpContext

Message


ENoResultSet methods

ENoResultSet	Alphabetically

In ENoResultSet

~ENoResultSet

ENoResultSet

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ENoResultSet methods

ENoResultSet	By object

~ENoResultSet

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ENoResultSet

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ENoResultSet::ENoResultSet

ENoResultSet	See also

ENoResultSet creates a new ENoResultSet object.

__fastcall ENoResultSet(const System::AnsiString Msg) : Db::EDatabaseError(Msg) { }

__fastcall ENoResultSet(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Msg, Args, Args_Size) { }

__fastcall ENoResultSet(int Ident, Extended Dummy) : Db::EDatabaseError(Ident, Dummy) { }

__fastcall ENoResultSet(int Ident, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Ident, Args, Args_Size) { }

__fastcall ENoResultSet(const System::AnsiString Msg, int AHelpContext) : Db::EDatabaseError(Msg, AHelpContext) { }

__fastcall ENoResultSet(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ENoResultSet(int Ident, int AHelpContext) : Db::EDatabaseError(Ident, AHelpContext) { }

__fastcall ENoResultSet(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Ident, Args, Args_Size, AHelpContext) { }

Description

ENoResultSet instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ENoResultSet("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


ENoResultSet::~ENoResultSet

ENoResultSet	See also

~ENoResultSet frees the memory associated with the ENoResultSet object.

__fastcall virtual ~ENoResultSet(void) { }

Description

Do not call ~ENoResultSet directly. Instead, use the delete keyword on the object, which causes ~ENoResultSet to be invoked automatically.


Hierarchy

TObject

Exception

EDatabaseError


EOleCtrlError

Hierarchy	Properties	Methods	See also

EOleCtrlError is the exception class for ActiveX controls.

Unit

olectrls

Description

EOleCtrlError is thrown when an application cannot link to an ActiveX control.


EOleCtrlError properties

EOleCtrlError	Alphabetically

Derived from Exception

HelpContext

Message


EOleCtrlError properties

EOleCtrlError	By object

HelpContext

Message


EOleCtrlError methods

EOleCtrlError	Alphabetically

In EOleCtrlError

~EOleCtrlError

EOleCtrlError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


EOleCtrlError methods

EOleCtrlError	By object

~EOleCtrlError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOleCtrlError

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


EOleCtrlError::EOleCtrlError

EOleCtrlError	See also

EOleCtrlError creates a new EOleCtrlError object.

__fastcall EOleCtrlError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EOleCtrlError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EOleCtrlError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EOleCtrlError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EOleCtrlError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EOleCtrlError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOleCtrlError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EOleCtrlError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EOleCtrlError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EOleCtrlError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EOleCtrlError::~EOleCtrlError

EOleCtrlError

~EOleCtrlError frees the memory associated with the EOleCtrlError object.

__fastcall virtual ~EOleCtrlError(void) { }

Description

Do not call ~EOleCtrlError directly. Instead, use the delete keyword on the object, which causes ~EOleCtrlError to be invoked automatically.


Hierarchy

TObject

Exception


EOleException

Hierarchy	Properties	Methods	See also

EOleException is the exception class for OLE automation errors that occur in methods or properties of an object.

Unit

comobj

Description

EOleException is the exception class for errors specific to the OLE IDispatch interface. EOleException is thrown when an error occurs in the middle of a method call from IDispatch. EOleException is generated when a C++Builder server receives a failure return value from a property or method that was called with the IDispatch interface Invoke method.

When an error occurs, objects invoked through IDispatch can return essential information about the exception, including the source of the error, error code, description, help file, and ID number for context-sensitive help. EOleException captures this information, and the error description and ID number (if available) are included in a message generated by the constructor; the other information is stored in the Source and HelpFile properties defined for EOleException and the ErrorCode property inherited from EOleSysError.


EOleException properties

EOleException	Alphabetically

In EOleException

HelpFile

Source

Derived from EOleSysError

ErrorCode

Derived from Exception

HelpContext

Message


EOleException properties

EOleException	By object

ErrorCode

HelpContext

HelpFile

Message

Source


EOleException::HelpFile

EOleException

Specifies the name and location of the help file that contains information about the error that occurred.

__property System::AnsiString HelpFile = {read=FHelpFile, write=FHelpFile};

Description

HelpFile lists the name and complete directory path of the help file that contains information about the error.


EOleException::Source

EOleException

Designates the application program in which the exception occurred.

__property System::AnsiString Source = {read=FSource, write=FSource};

Description

Source gives the source of the exception. Usually, this is the name of an application program.


EOleException methods

EOleException	Alphabetically

In EOleException

~EOleException

EOleException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOleException methods

EOleException	By object

~EOleException

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOleException

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOleException::EOleException

EOleException	See also

Creates an EOleException object.

__fastcall EOleException(const System::AnsiString Message, int ErrorCode, const System::AnsiString

__fastcall EOleException(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Comobj::EOleSysError(Msg, Args, Args_Size) { }

__fastcall EOleException(int Ident, Extended Dummy) : Comobj::EOleSysError(Ident, Dummy) { }

__fastcall EOleException(int Ident, const System::TVarRec * Args, const int Args_Size) : Comobj::EOleSysError(Ident, Args, Args_Size) { }

__fastcall EOleException(const System::AnsiString Msg, int AHelpContext) : Comobj::EOleSysError(Msg, AHelpContext) { }

__fastcall EOleException(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Comobj::EOleSysError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOleException(int Ident, int AHelpContext) : Comobj::EOleSysError(Ident, AHelpContext) { }

__fastcall EOleException(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Comobj::EOleSysError(Ident, Args, Args_Size, AHelpContext) { }

Description

EOleException instantiates an EOleException object. It allocates memory for the exception and initializes the ErrorCode, HelpFile, and Source properties using information passed in the OLE EXCEPINFO structure. It then calls the parent’s constructor method to display the error description and ID number from EXCEPINFO.

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.

Always use the throw keyword with the constructor.


EOleException::~EOleException

EOleException

~EOleException frees the memory associated with the EOleException object.

__fastcall virtual ~EOleException(void) { }

Description

Do not call ~EOleException directly. Instead, use the delete keyword on the object, which causes ~EOleException to be invoked automatically.


Hierarchy

TObject

Exception

EOleError

EOleSysError


EOleError

Hierarchy	Properties	Methods	See also

EOleError is the exception class for low-level OLE errors.

Unit

comobj

Description

EOleError is thrown when the system returns a non-zero HRESULT involving low-level and old OLE 2 errors. C++Builder checks for, but does not generate, these exceptions.


EOleError properties

EOleError	Alphabetically

Derived from Exception

HelpContext

Message


EOleError properties

EOleError	By object

HelpContext

Message


EOleError methods

EOleError	Alphabetically

In EOleError

~EOleError

EOleError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOleError methods

EOleError	By object

~EOleError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOleError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOleError::EOleError

EOleError	See also

EOleError creates a new EOleError object.

__fastcall EOleError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EOleError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EOleError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EOleError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EOleError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EOleError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOleError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EOleError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EOleError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EOleError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EOleError::~EOleError

EOleError

~EOleError frees the memory associated with the EOleError object.

__fastcall virtual ~EOleError(void) { }

Description

Do not call ~EOleError directly. Instead, use the delete keyword on the object, which causes ~EOleError to be invoked automatically.


Hierarchy

TObject

Exception


EOleSysError

Hierarchy	Properties	Methods

EOleSysError is the exception class errors specific to the OLE IDispatch interface.

Unit

comobj

Description

EOleSysError is the exception class for errors that occur during an attempt to invoke a method or property of an OLE automation object. When the IDispatch Invoke method fails, EOleSysError is thrown. Objects invoked through IDispatch can return the error code—an OLE status code or SCODE—indicating the reason for the error.


EOleSysError properties

EOleSysError	Alphabetically

In EOleSysError

ErrorCode

Derived from Exception

HelpContext

Message


EOleSysError properties

EOleSysError	By object

ErrorCode

HelpContext

Message


EOleSysError::ErrorCode

EOleSysError	See also

The status code returned by the failed method call, indicating the reason for the failure.

__property int ErrorCode = {read=FErrorCode, write=FErrorCode, nodefault};

Description

ErrorCode is the numerical error code returned by a failed call to an OLE automation object’s method or property.

ErrorCode is initialized in the constructor.


EOleSysError methods

EOleSysError	Alphabetically

In EOleSysError

~EOleSysError

EOleSysError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOleSysError methods

EOleSysError	By object

~EOleSysError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOleSysError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOleSysError::EOleSysError

EOleSysError	See also

Creates an EOleSysError object.

__fastcall EOleSysError(const System::AnsiString Message, int ErrorCode, int HelpContext);

__fastcall EOleSysError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Comobj::EOleError(Msg, Args, Args_Size) { }

__fastcall EOleSysError(int Ident, Extended Dummy) : Comobj::EOleError(Ident, Dummy) { }

__fastcall EOleSysError(int Ident, const System::TVarRec * Args, const int Args_Size) : Comobj::EOleError(Ident, Args, Args_Size) { }

__fastcall EOleSysError(const System::AnsiString Msg, int AHelpContext) : Comobj::EOleError(Msg, AHelpContext) { }

__fastcall EOleSysError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Comobj::EOleError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOleSysError(int Ident, int AHelpContext) : Comobj::EOleError(Ident, AHelpContext) { }

__fastcall EOleSysError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Comobj::EOleError(Ident, Args, Args_Size, AHelpContext) { }

Description

EOleSysError instantiates an exception object with a simple message string. It calls SysErrorMessage to turn the OLE error code, ErrorCode, into a message string which it passes to the inherited constructor. EOleSysError initializes the ErrorCode property to the ErrorCode string.

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.

Always use the throw keyword with the constructor.


EOleSysError::~EOleSysError

EOleSysError

~EOleSysError frees the memory associated with the EOleSysError object.

__fastcall virtual ~EOleSysError(void) { }

Description

Do not call ~EOleSysError directly. Instead, use the delete keyword on the object, which causes ~EOleSysError to be invoked automatically.


Hierarchy

TObject

Exception

EOleError


EOutlineError

Hierarchy	Properties	Methods	See also

EOutlineError is the exception class for outline components.

Unit

outline

Description

EOutlineError is thrown when an error occurs as an application works with an outline component. For example, an EOutlineError exception occurs when an application

•	Attempts to access an outline using an invalid node index.

•	Attempts to expand a node whose parent isn’t expanded.

•	Attempts to load items from a file using an invalid file extension.

Note

EOutlineError is thrown by the TOutline component, which is maintained for compatibility with older versions of the VCL only.


EOutlineError properties

EOutlineError	Alphabetically

Derived from Exception

HelpContext

Message


EOutlineError properties

EOutlineError	By object

HelpContext

Message


EOutlineError methods

EOutlineError	Alphabetically

In EOutlineError

~EOutlineError

EOutlineError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOutlineError methods

EOutlineError	By object

~EOutlineError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOutlineError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOutlineError::EOutlineError

EOutlineError	See also

EOutlineError creates a new EOutlineError object.

__fastcall EOutlineError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EOutlineError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EOutlineError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EOutlineError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EOutlineError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EOutlineError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOutlineError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EOutlineError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EOutlineError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EOutlineError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EOutlineError::~EOutlineError

EOutlineError

~EOutlineError frees the memory associated with the EOutlineError object.

__fastcall virtual ~EOutlineError(void) { }

Description

Do not call ~EOutlineError directly. Instead, use the delete keyword on the object, which causes ~EOutlineError to be invoked automatically.


Hierarchy

TObject

Exception


EOutlineError example

EOutlineError


EOutOfMemory

Hierarchy	Properties	Methods	See also

EOutOfMemory is the exception class for unsuccessful attempts to allocate memory.

Unit

sysutils

Description

EOutOfMemory is thrown when an application attempts to allocate dynamic memory, but there is not enough free memory in the system to meet the request.

Memory for the EOutOfMemory exception is itself preallocated whenever a C++Builder application starts and remains allocated as long as the application is running.

Note

Never throw EOutOfMemory directly. Instead, use the OutOfMemoryError function.


EOutOfMemory properties

EOutOfMemory	Alphabetically

Derived from Exception

HelpContext

Message


EOutOfMemory properties

EOutOfMemory	By object

HelpContext

Message


EOutOfMemory methods

EOutOfMemory	Alphabetically

In EOutOfMemory

~EOutOfMemory

EOutOfMemory

FreeInstance

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOutOfMemory methods

EOutOfMemory	By object

~EOutOfMemory

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOutOfMemory

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOutOfMemory::~EOutOfMemory

EOutOfMemory

The ~EOutOfMemory method is inoperative.

__fastcall virtual ~EOutOfMemory(void);

Description

EOutOfMemory overrides the parent object’s destructor method. Memory for this exception is preallocated when an application starts and should remain allocated as long as the application is running. For this reason, the ~EOutOfMemory method has been disabled; calling ~EOutOfMemory has no effect on an EOutOfMemory object.


EOutOfMemory::FreeInstance

EOutOfMemory

The FreeInstance method for EOutOfMemory is inoperative.

virtual void __fastcall FreeInstance(void);

Description

EOutOfMemory overrides the inherited FreeInstance method. Memory for this exception is preallocated when an application starts and should remain allocated as long as the application is running. For this reason, the FreeInstance method has been disabled; calling FreeInstance has no effect on an EOutOfMemory object.


EOutOfMemory::EOutOfMemory

EOutOfMemory	See also

EOutOfMemory creates a new EOutOfMemory object.

__fastcall EOutOfMemory(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EOutOfMemory(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EOutOfMemory(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EOutOfMemory(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EOutOfMemory(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EOutOfMemory(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOutOfMemory(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EOutOfMemory(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

Do not instantiate EOutOfMemory directly. Instead, use the OutOfMemoryError function.


Hierarchy

TObject

Exception


EOutOfMemory example

EOutOfMemory


EOutOfResources

Hierarchy	Properties	Methods	See also

EOutOfResources is the exception class for unsuccessful attempts to allocate Windows handles.

Unit

classes

Description

EOutOfResources is thrown when an application attempts to create a Windows handle and Windows has no more handles to allocate.


EOutOfResources properties

EOutOfResources	Alphabetically

Derived from Exception

HelpContext

Message


EOutOfResources properties

EOutOfResources	By object

HelpContext

Message


EOutOfResources methods

EOutOfResources	Alphabetically

In EOutOfResources

~EOutOfResources

EOutOfResources

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOutOfResources methods

EOutOfResources	By object

~EOutOfResources

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOutOfResources

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOutOfResources::EOutOfResources

EOutOfResources	See also

EOutOfResources creates a new EOutOfResources object.

__fastcall EOutOfResources(const System::AnsiString Msg) : Sysutils::EOutOfMemory(Msg) { }

__fastcall EOutOfResources(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EOutOfMemory(Msg, Args, Args_Size) { }

__fastcall EOutOfResources(int Ident, Extended Dummy) : Sysutils::EOutOfMemory(Ident, Dummy) { }

__fastcall EOutOfResources(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EOutOfMemory(Ident, Args, Args_Size) { }

__fastcall EOutOfResources(const System::AnsiString Msg, int AHelpContext) : Sysutils::EOutOfMemory(Msg, AHelpContext) { }

__fastcall EOutOfResources(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EOutOfMemory(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOutOfResources(int Ident, int AHelpContext) : Sysutils::EOutOfMemory(Ident, AHelpContext) { }

__fastcall EOutOfResources(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EOutOfMemory(Ident, Args, Args_Size, AHelpContext) { }

Description

EOutOfResources instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EOutOfResources("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EOutOfResources::~EOutOfResources

EOutOfResources

~EOutOfResources frees the memory associated with the EOutOfResources object.

__fastcall virtual ~EOutOfResources(void) { }

Description

Do not call ~EOutOfResources directly. Instead, use the delete keyword on the object, which causes ~EOutOfResources to be invoked automatically.


Hierarchy

TObject

Exception

EOutOfMemory


EOverflow

Hierarchy	Properties	Methods	See also

EOverflow is the exception class for floating-point register overflows.

Unit

sysutils

Description

EOverflow is thrown when a calculated result is too large to fit in the floating-point register allocated for it and data is therefore lost.

As a descendant of EExternal, EOverflow saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EOverflow properties

EOverflow	Alphabetically

Derived from Exception

HelpContext

Message


EOverflow properties

EOverflow	By object

HelpContext

Message


EOverflow methods

EOverflow	Alphabetically

In EOverflow

~EOverflow

EOverflow

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOverflow methods

EOverflow	By object

~EOverflow

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EOverflow

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EOverflow::EOverflow

EOverflow	See also

EOverflow creates a new EOverflow object.

__fastcall EOverflow(const System::AnsiString Msg) : Sysutils::EMathError(Msg) { }

__fastcall EOverflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Msg, Args, Args_Size) { }

__fastcall EOverflow(int Ident, Extended Dummy) : Sysutils::EMathError(Ident, Dummy) { }

__fastcall EOverflow(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Ident, Args, Args_Size) { }

__fastcall EOverflow(const System::AnsiString Msg, int AHelpContext) : Sysutils::EMathError(Msg, AHelpContext) { }

__fastcall EOverflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EOverflow(int Ident, int AHelpContext) : Sysutils::EMathError(Ident, AHelpContext) { }

__fastcall EOverflow(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Ident, Args, Args_Size, AHelpContext) { }

Description

EOverflow instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EOverflow("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EOverflow::~EOverflow

EOverflow

~EOverflow frees the memory associated with the EOverflow object.

__fastcall virtual ~EOverflow(void) { }

Description

Do not call ~EOverflow directly. Instead, use the delete keyword on the object, which causes ~EOverflow to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EMathError


EOverflow example

EOverflow


EParserError

Hierarchy	Properties	Methods	See also

EParserError is the exception class for text-to-binary streaming conversion errors.

Unit

classes

Description

EParserError is thrown when an error occurs during text-to-binary conversion, usually due to a syntax error in the source text.


EParserError properties

EParserError	Alphabetically

Derived from Exception

HelpContext

Message


EParserError properties

EParserError	By object

HelpContext

Message


EParserError methods

EParserError	Alphabetically

In EParserError

~EParserError

EParserError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EParserError methods

EParserError	By object

~EParserError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EParserError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EParserError::EParserError

EParserError	See also

EParserError creates a new EParserError object.

__fastcall EParserError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EParserError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EParserError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EParserError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EParserError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EParserError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EParserError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EParserError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EParserError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EParserError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EParserError::~EParserError

EParserError

~EParserError frees the memory associated with the EParserError object.

__fastcall virtual ~EParserError(void) { }

Description

Do not call ~EParserError directly. Instead, use the delete keyword on the object, which causes ~EParserError to be invoked automatically.


Hierarchy

TObject

Exception


EParserError example

EParserError


EPackageError

Hierarchy	Properties	Methods

EPackageError is the exception class for package-related errors.

Unit

sysutils

Description

EPackageError is thrown at design time only, when an error occurs loading or utilizing a package.


EPackageError properties

EPackageError	Alphabetically

Derived from Exception

HelpContext

Message


EPackageError properties

EPackageError	By object

HelpContext

Message


EPackageError methods

EPackageError	Alphabetically

In EPackageError

~EPackageError

EPackageError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPackageError methods

EPackageError	By object

~EPackageError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EPackageError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPackageError::EPackageError

EPackageError	See also

EPackageError creates a new EPackageError object.

__fastcall EPackageError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EPackageError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EPackageError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EPackageError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EPackageError(const System::AnsiString Msg, int AHelpContext): Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EPackageError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EPackageError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EPackageError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext){ }

Description

EPackageError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EPackageError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EPackageError::~EPackageError

EPackageError	See also

~EPackageError frees the memory associated with the EPackageError object.

__fastcall virtual ~EPackageError(void) { }

Description

Do not call ~EPackageError directly. Instead, use the delete keyword on the object, which causes ~EPackageError to be invoked automatically.


Hierarchy

TObject

Exception


EPrinter

Hierarchy	Properties	Methods

EPrinter is the exception class for printing errors.

Unit

printers

Description

EPrinter is thrown when a printing error occurs. For example, if an application attempts to use a printer that doesn’t exist, or if a job can’t be sent to the printer for some other reason, an EPrinter exception is thrown.


EPrinter properties

EPrinter	Alphabetically

Derived from Exception

HelpContext

Message


EPrinter properties

EPrinter	By object

HelpContext

Message


EPrinter methods

EPrinter	Alphabetically

In EPrinter

~EPrinter

EPrinter

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPrinter methods

EPrinter	By object

~EPrinter

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EPrinter

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPrinter::EPrinter

EPrinter	See also

EPrinter creates a new EPrinter object.

__fastcall EPrinter(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EPrinter(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EPrinter(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EPrinter(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EPrinter(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EPrinter(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EPrinter(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EPrinter(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EPrinter instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EPrinter("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EPrinter::~EPrinter

EPrinter

~EPrinter frees the memory associated with the EPrinter object.

__fastcall virtual ~EPrinter(void) { }

Description

Do not call ~EPrinter directly. Instead, use the delete keyword on the object, which causes ~EPrinter to be invoked automatically.


Hierarchy

TObject

Exception


EPrinter example

EPrinter


EPrivilege

Hierarchy	Properties	Methods	See also

EPrivilege is the exception class for processor privilege violations.

Unit

sysutils

Description

EPrivilege is thrown when an application tries to execute a processor instruction that is invalid for the current processor privilege level.

As a descendant of EExternal, EPrivilege saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EPrivilege properties

EPrivilege	Alphabetically

Derived from Exception

HelpContext

Message


EPrivilege properties

EPrivilege	By object

HelpContext

Message


EPrivilege methods

EPrivilege	Alphabetically

In EPrivilege

~EPrivilege

EPrivilege

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPrivilege methods

EPrivilege	By object

~EPrivilege

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EPrivilege

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPrivilege::EPrivilege

EPrivilege	See also

EPrivilege creates a new EPrivilege object.

__fastcall EPrivilege(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EPrivilege(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EPrivilege(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EPrivilege(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EPrivilege(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EPrivilege(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EPrivilege(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EPrivilege(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EPrivilege instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EPrivilege("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EPrivilege::~EPrivilege

EPrivilege

~EPrivilege frees the memory associated with the EPrivilege object.

__fastcall virtual ~EPrivilege(void) { }

Description

Do not call ~EPrivilege directly. Instead, use the delete keyword on the object, which causes ~EPrivilege to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EPrivilege example

EPrivilege


EPropertyError

Hierarchy	Properties	Methods	See also

EPropertyError is the exception class for unsuccessful attempts to set the value of a property.

Unit

dsgnintf

Description

EPropertyError is thrown by the SetValue (or Edit) methods of property-editor objects when they cannot set a requested property value. This usually occurs because the requested value is out of range or of an invalid data type.


EPropertyError properties

EPropertyError	Alphabetically

Derived from Exception

HelpContext

Message


EPropertyError properties

EPropertyError	By object

HelpContext

Message


EPropertyError methods

EPropertyError	Alphabetically

In EPropertyError

~EPropertyError

EPropertyError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPropertyError methods

EPropertyError	By object

~EPropertyError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EPropertyError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPropertyError::EPropertyError

EPropertyError	See also

EPropertyError creates a new EPropertyError object.

__fastcall EPropertyError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EPropertyError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EPropertyError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EPropertyError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EPropertyError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EPropertyError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EPropertyError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EPropertyError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EPropertyError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EPropertyError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EPropertyError::~EPropertyError

EPropertyError

~EPropertyError frees the memory associated with the EPropertyError object.

__fastcall virtual ~EPropertyError(void) { }

Description

Do not call ~EPropertyError directly. Instead, use the delete keyword on the object, which causes ~EPropertyError to be invoked automatically.


Hierarchy

TObject

Exception


EPropReadOnly

Hierarchy	Properties	Methods

EPropReadOnly is the exception class for invalid attempts to write to a property using OLE automation.

Unit

sysutils

Description

EPropReadOnly is thrown when an application tries to write to a read-only property using OLE automation.


EPropReadOnly properties

EPropReadOnly	Alphabetically

Derived from Exception

HelpContext

Message


EPropReadOnly properties

EPropReadOnly	By object

HelpContext

Message


EPropReadOnly methods

EPropReadOnly	Alphabetically

In EPropReadOnly

~EPropReadOnly

EPropReadOnly

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPropReadOnly methods

EPropReadOnly	By object

~EPropReadOnly

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EPropReadOnly

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPropReadOnly::EPropReadOnly

EPropReadOnly	See also

EPropReadOnly creates a new EPropReadOnly object.

__fastcall EPropReadOnly(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EPropReadOnly(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EPropReadOnly(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EPropReadOnly(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EPropReadOnly(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EPropReadOnly(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EPropReadOnly(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EPropReadOnly(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EPropReadOnly instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EPropReadOnly("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EPropReadOnly::~EPropReadOnly

EPropReadOnly

~EPropReadOnly frees the memory associated with the EPropReadOnly object.

__fastcall virtual ~EPropReadOnly(void) { }

Description

Do not call ~EPropReadOnly directly. Instead, use the delete keyword on the object, which causes ~EPropReadOnly to be invoked automatically.


Hierarchy

TObject

Exception


EPropReadOnly example

EPropReadOnly


EPropWriteOnly

Hierarchy	Properties	Methods

EPropWriteOnly is the exception class for invalid attempts to read a property using OLE automation.

Unit

sysutils

Description

EPropWriteOnly is thrown when an application tries to read a write-only property using OLE automation.


EPropWriteOnly properties

EPropWriteOnly	Alphabetically

Derived from Exception

HelpContext

Message


EPropWriteOnly properties

EPropWriteOnly	By object

HelpContext

Message


EPropWriteOnly methods

EPropWriteOnly	Alphabetically

In EPropWriteOnly

~EPropWriteOnly

EPropWriteOnly

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPropWriteOnly methods

EPropWriteOnly	By object

~EPropWriteOnly

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EPropWriteOnly

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EPropWriteOnly::EPropWriteOnly

EPropWriteOnly	See also

EPropWriteOnly creates a new EPropWriteOnly object.

__fastcall EPropWriteOnly(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EPropWriteOnly(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EPropWriteOnly(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EPropWriteOnly(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EPropWriteOnly(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EPropWriteOnly(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EPropWriteOnly(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EPropWriteOnly(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EPropWriteOnly instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EPropWriteOnly("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EPropWriteOnly::~EPropWriteOnly

EPropWriteOnly

~EPropWriteOnly frees the memory associated with the EPropWriteOnly object.

__fastcall virtual ~EPropWriteOnly(void) { }

Description

Do not call ~EPropWriteOnly directly. Instead, use the delete keyword on the object, which causes ~EPropWriteOnly to be invoked automatically.


Hierarchy

TObject

Exception


EPropWriteOnly example

EPropWriteOnly


ERangeError

Hierarchy	Properties	Methods	See also

ERangeError is the exception class for integer values that are too large for the declared type to which they are assigned.

Unit

sysutils

Description

ERangeError is an integer math exception. It occurs when

•	An integer expression’s value exceeds the bounds of the specified integer type to which it is assigned.

•	Source code attempts to access an item in an array using an index value that is not within the defined array.

As a descendant of EExternal, ERangeError saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


ERangeError properties

ERangeError	Alphabetically

Derived from Exception

HelpContext

Message


ERangeError properties

ERangeError	By object

HelpContext

Message


ERangeError methods

ERangeError	Alphabetically

In ERangeError

~ERangeError

ERangeError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ERangeError methods

ERangeError	By object

~ERangeError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ERangeError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ERangeError::ERangeError

ERangeError	See also

ERangeError creates a new ERangeError object.

__fastcall ERangeError(const System::AnsiString Msg) : Sysutils::EIntError(Msg) { }

__fastcall ERangeError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EIntError(Msg, Args, Args_Size) { }

__fastcall ERangeError(int Ident, Extended Dummy) : Sysutils::EIntError(Ident, Dummy) { }

__fastcall ERangeError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EIntError(Ident, Args, Args_Size) { }

__fastcall ERangeError(const System::AnsiString Msg, int AHelpContext) : Sysutils::EIntError(Msg, AHelpContext) { }

__fastcall ERangeError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EIntError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ERangeError(int Ident, int AHelpContext) : Sysutils::EIntError(Ident, AHelpContext) { }

__fastcall ERangeError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EIntError(Ident, Args, Args_Size, AHelpContext) { }

Description

ERangeError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ERangeError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


ERangeError::~ERangeError

ERangeError

~ERangeError frees the memory associated with the ERangeError object.

__fastcall virtual ~ERangeError(void) { }

Description

Do not call ~ERangeError directly. Instead, use the delete keyword on the object, which causes ~ERangeError to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EIntError


ERangeError example

ERangeError


EReadError

Hierarchy	Properties	Methods	See also

EReadError is the exception class for unsuccessful attempts to read data from a stream.

Unit

classes

Description

EReadError is thrown when an application attempts to read data from a stream but cannot read the specified number of bytes.

An EReadError exception may also be thrown if C++Builder is unable to read a property while creating a form. This can occur because a component reads the form resource incorrectly, or because the resource is corrupt.


EReadError properties

EReadError	Alphabetically

Derived from Exception

HelpContext

Message


EReadError properties

EReadError	By object

HelpContext

Message


EReadError methods

EReadError	Alphabetically

In EReadError

~EReadError

EReadError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EReadError methods

EReadError	By object

~EReadError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EReadError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EReadError::EReadError

EReadError	See also

EReadError creates a new EReadError object.

__fastcall EReadError(const System::AnsiString Msg) : Classes::EFilerError(Msg) { }

__fastcall EReadError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Msg, Args, Args_Size) { }

__fastcall EReadError(int Ident, Extended Dummy) : Classes::EFilerError(Ident, Dummy) { }

__fastcall EReadError(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Ident, Args, Args_Size) { }

__fastcall EReadError(const System::AnsiString Msg, int AHelpContext) : Classes::EFilerError(Msg, AHelpContext) { }

__fastcall EReadError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EReadError(int Ident, int AHelpContext) : Classes::EFilerError(Ident, AHelpContext) { }

__fastcall EReadError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Ident, Args, Args_Size, AHelpContext) { }

Description

EReadError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EReadError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EReadError::~EReadError

EReadError

~EReadError frees the memory associated with the EReadError object.

__fastcall virtual ~EReadError(void) { }

Description

Do not call ~EReadError directly. Instead, use the delete keyword on the object, which causes ~EReadError to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError

EFilerError


EReconcileError

Hierarchy	Properties	Methods	See also

EReconcileError is the exception class for client dataset errors.

Unit

dbclient

Description

EReconcileError is thrown if an error occurs when updates are being applied from a TClientDataSet.


EReconcileError properties

EReconcileError	Alphabetically	Legend

In EReconcileError

Context

Derived from EDBClient

ErrorCode

Derived from Exception

HelpContext

Message


EReconcileError properties

EReconcileError	By object	Legend

Context

ErrorCode

HelpContext

Message


EReconcileError::Context

EReconcileError	See also

Contains context information from the error stack.

__property System::AnsiString Context = {read=FContext};

Description

Context contains additional information returned with the error message.


EReconcileError methods

EReconcileError	Alphabetically

In EReconcileError

~EReconcileError

EReconcileError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EReconcileError methods

EReconcileError	By object

~EReconcileError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EReconcileError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EReconcileError::EReconcileError

EReconcileError	See also

Initializes an instance of EReconcileError using error information returned by the BDE.

__fastcall EReconcileError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Dbclient::EDBClient(Msg, Args, Args_Size) { }

__fastcall EReconcileError(int Ident, Extended Dummy) : Dbclient::EDBClient(Ident, Dummy) { }

__fastcall EReconcileError(int Ident, const System::TVarRec * Args, const int Args_Size) : Dbclient::EDBClient(Ident, Args, Args_Size) { }

__fastcall EReconcileError(const System::AnsiString Msg, int AHelpContext) : Dbclient::EDBClient(Msg, AHelpContext) { }

__fastcall EReconcileError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Dbclient::EDBClient(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EReconcileError(int Ident, int AHelpContext) : Dbclient::EDBClient(Ident, AHelpContext) { }

__fastcall EReconcileError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Dbclient::EDBClient(Ident, Args, Args_Size, AHelpContext) { }

Description

EReconcileError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EReconcileError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EReconcileError::~EReconcileError

EReconcileError	See also

~EReconcileError frees the memory associated with the EReconcileError object.

__fastcall virtual ~EReconcileError(void) { }

Description

Do not call ~EReconcileError directly. Instead, use the delete keyword on the object, which causes ~EReconcileError to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

Exception

EDatabaseError

EDBClient


ERegistryException

Hierarchy	Properties	Methods	See also

ERegistryException is the exception class for registry errors.

Unit

registry

Description

ERegistryException is raised when an application cannot

•	Create a new key in the registry.

•	Read a data value associated with a key.

•	Read a binary data value associated with a key into a local buffer.

•	Write a data value to a key.

Key creation fails when an application attempts to create a subkey under a key for which it does not have KEY_CREATE_SUB_KEY security access.

Reading a data value associated with a key fails when an application does not have KEY_READ security access, or when the application attempts to read the wrong kind of data from a key (for example, attempting to read string data from an integer data value).

Reading a binary data value into a local buffer fails when an application does not allocate a buffer large enough for the data.

Writing a data value to a key fails because an application does not have KEY_WRITE security access for the current key.


ERegistryException properties

ERegistryException	Alphabetically

Derived from Exception

HelpContext

Message


ERegistryException properties

ERegistryException	By object

HelpContext

Message


ERegistryException methods

ERegistryException	Alphabetically

In ERegistryException

~ERegistryException

ERegistryException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


ERegistryException methods

ERegistryException	By object

~ERegistryException

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ERegistryException

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


ERegistryException::ERegistryException

ERegistryException	See also

ERegistryException creates a new ERegistryException object.

__fastcall ERegistryException(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall ERegistryException(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall ERegistryException(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall ERegistryException(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall ERegistryException(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall ERegistryException(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ERegistryException(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall ERegistryException(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

ERegistryException instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ERegistryException("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


ERegistryException::~ERegistryException

ERegistryException	See also

~ERegistryException frees the memory associated with the ERegistryException object.

__fastcall virtual ~ERegistryException(void) { }

Description

Do not call ~ERegistryException directly. Instead, use the delete keyword on the object, which causes ~ERegistryException to be invoked automatically.


Hierarchy

TObject

Exception


ERegistryException example

ERegistryException


EResNotFound

Hierarchy	Properties	Methods	See also

EResNotFound is the exception class for unlocatable resources.

Unit

classes

Description

EResNotFound is thrown when C++Builder cannot find a specified resource (such as a form, bitmap, or icon) in a .DFM or .RES file, or when the resource is not linked into the application.

If you receive this exception on startup of an application, or when you create a form, check the form’s source file for the #pragma resource "*.dfm" directive. If this directive is missing or commented out, the .DFM file will not be included in the executable and an EResNotFound exception will be generated.


EResNotFound properties

EResNotFound	Alphabetically

Derived from Exception

HelpContext

Message


EResNotFound properties

EResNotFound	By object

HelpContext

Message


EResNotFound methods

EResNotFound	Alphabetically

In EResNotFound

~EResNotFound

EResNotFound

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EResNotFound methods

EResNotFound	By object

~EResNotFound

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EResNotFound

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EResNotFound::EResNotFound

EResNotFound	See also

EResNotFound creates a new EResNotFound object.

__fastcall EResNotFound(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EResNotFound(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EResNotFound(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EResNotFound(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EResNotFound(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EResNotFound(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EResNotFound(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EResNotFound(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EResNotFound instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EResNotFound("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EResNotFound::~EResNotFound

EResNotFound

~EResNotFound frees the memory associated with the EResNotFound object.

__fastcall virtual ~EResNotFound(void) { }

Description

Do not call ~EResNotFound directly. Instead, use the delete keyword on the object, which causes ~EResNotFound to be invoked automatically.


Hierarchy

TObject

Exception


EResNotFound example

EResNotFound


ERemoteSocketError

Hierarchy	Properties	Methods	See also

ERemoteSocketError is the exception class for failures that occur when trying to read to or write from a socket dispatcher.

Unit

MIDASCon

Description

ERemoteSocketError is thrown when the information read from or written to a TSocketDispatcher object is not in the expected format. This error can arise if the port of the socket used by the socket stream is associated with another service, or if there is an error in the implementation of the IDispatch interface by a COM object.


ERemoteSocketError properties

ERemoteSocketError	Alphabetically

Derived from Exception

HelpContext

Message


ERemoteSocketError properties

ERemoteSocketError	By object

HelpContext

Message


ERemoteSocketError methods

ERemoteSocketError	Alphabetically

In ERemoteSocketError

~ERemoteSocketError

ERemoteSocketError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ERemoteSocketError methods

ERemoteSocketError	By object

~ERemoteSocketError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ERemoteSocketError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ERemoteSocketError::ERemoteSocketError

ERemoteSocketError	See also

ERemoteSocketError creates a new ERemoteSocketError object.

__fastcall ERemoteSocketError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall ERemoteSocketError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall ERemoteSocketError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall ERemoteSocketError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall ERemoteSocketError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall ERemoteSocketError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ERemoteSocketError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall ERemoteSocketError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

ERemoteSocketError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ERemoteSocketError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


ERemoteSocketError::~ERemoteSocketError

ERemoteSocketError	See also

~ERemoteSocketError frees the memory associated with the ERemoteSocketError object.

__fastcall virtual ~ERemoteSocketError(void) { };

Description

Do not call ~ERemoteSocketError directly. Instead, use the delete keyword on the object, which causes ~ERemoteSocketError to be invoked automatically.


Hierarchy

TObject

Exception


ESocketError

Hierarchy	Properties	Methods	See also

ESocketError is the exception class for failures that occur when trying to create, use, or shut down Windows socket objects.

Unit

scktcomp

Description

ESocketError is thrown if

•	A socket cannot be created.

•	A socket cannot be initialized.

•	A socket cannot be opened.

•	An application tries to change the properties of an already open socket.

•	A failure occurs when reading from or writing to a socket.

•	A socket cannot be properly closed.


ESocketError properties

ESocketError	Alphabetically

Derived from Exception

HelpContext

Message


ESocketError properties

ESocketError	By object

HelpContext

Message


ESocketError methods

ESocketError	Alphabetically

In ESocketError

~ESocketError

ESocketError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ESocketError methods

ESocketError	By object

~ESocketError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ESocketError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ESocketError::ESocketError

ESocketError	See also

ESocketError creates a new ESocketError object.

__fastcall ESocketError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall ESocketError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall ESocketError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall ESocketError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall ESocketError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall ESocketError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ESocketError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall ESocketError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

ESocketError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ESocketError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


ESocketError::~ESocketError

ESocketError	See also

~ESocketError frees the memory associated with the ESocketError object.

__fastcall virtual ~ESocketError(void) { }

Description

Do not call ~ESocketError directly. Instead, use the delete keyword on the object, which causes ~ESocketError to be invoked automatically.


Hierarchy

TObject

Exception


EStackOverflow

Hierarchy	Properties	Methods	See also

EStackOverflow is the exception class for stack overflows.

Unit

sysutils

Description

EStackOverflow is thrown when the current thread’s stack grows into the final guard page—that is, when the system cannot grow the stack dynamically. This can happen because of extremely large local variables, deeply recursive routines, or invalid assembly-language code.

As a descendant of EExternal, EStackOverflow saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EStackOverflow properties

EStackOverflow	Alphabetically

Derived from Exception

HelpContext

Message


EStackOverflow properties

EStackOverflow	By object

HelpContext

Message


EStackOverflow methods

EStackOverflow	Alphabetically

In EStackOverflow

~EStackOverflow

EStackOverflow

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EStackOverflow methods

EStackOverflow	By object

~EStackOverflow

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EStackOverflow

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EStackOverflow::EStackOverflow

EStackOverflow	See also

EStackOverflow creates a new EStackOverflow object.

__fastcall EStackOverflow(const System::AnsiString Msg) : Sysutils::EExternal(Msg) { }

__fastcall EStackOverflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Msg, Args, Args_Size) { }

__fastcall EStackOverflow(int Ident, Extended Dummy) : Sysutils::EExternal(Ident, Dummy) { }

__fastcall EStackOverflow(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EExternal(Ident, Args, Args_Size) { }

__fastcall EStackOverflow(const System::AnsiString Msg, int AHelpContext) : Sysutils::EExternal(Msg, AHelpContext) { }

__fastcall EStackOverflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EStackOverflow(int Ident, int AHelpContext) : Sysutils::EExternal(Ident, AHelpContext) { }

__fastcall EStackOverflow(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EExternal(Ident, Args, Args_Size, AHelpContext) { }

Description

EStackOverflow instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EStackOverflow("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EStackOverflow::~EStackOverflow

EStackOverflow

~EStackOverflow frees the memory associated with the EStackOverflow object.

__fastcall virtual ~EStackOverflow(void) { }

Description

Do not call ~EStackOverflow directly. Instead, use the delete keyword on the object, which causes ~EStackOverflow to be invoked automatically.


Hierarchy

TObject

Exception

EExternal


EStackOverflow example

EStackOverflow


EStringListError

Hierarchy	Properties	Methods	See also

EStringListError is the exception class for invalid list-box references.

Unit

classes

Description

EStringListError is thrown when an application attempts to access a list box (for example, to add an item) using an invalid index.


EStringListError properties

EStringListError	Alphabetically

Derived from Exception

HelpContext

Message


EStringListError properties

EStringListError	By object

HelpContext

Message


EStringListError methods

EStringListError	Alphabetically

In EStringListError

~EStringListError

EStringListError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EStringListError methods

EStringListError	By object

~EStringListError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EStringListError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EStringListError::EStringListError

EStringListError	See also

EStringListError creates a new EStringListError object.

__fastcall EStringListError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EStringListError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EStringListError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EStringListError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EStringListError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EStringListError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EStringListError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EStringListError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EStringListError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EStringListError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EStringListError::~EStringListError

EStringListError

~EStringListError frees the memory associated with the EStringListError object.

__fastcall virtual ~EStringListError(void) { }

Description

Do not call ~EStringListError directly. Instead, use the delete keyword on the object, which causes ~EStringListError to be invoked automatically.


Hierarchy

TObject

Exception


EStringListError example

EStringListError


EStreamError

Hierarchy	Properties	Methods	See also

EStreamError is the exception class for streaming errors.

Unit

classes

Description

EStreamError is the ancestor from which all streaming exception classes descend. EStreamError is itself thrown when resources cannot be allocated for a memory stream.


EStreamError properties

EStreamError	Alphabetically

Derived from Exception

HelpContext

Message


EStreamError properties

EStreamError	By object

HelpContext

Message


EStreamError methods

EStreamError	Alphabetically

In EStreamError

~EStreamError

EStreamError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EStreamError methods

EStreamError	By object

~EStreamError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EStreamError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EStreamError::EStreamError

EStreamError	See also

EStreamError creates a new EStreamError object.

__fastcall EStreamError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EStreamError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EStreamError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EStreamError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EStreamError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EStreamError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EStreamError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EStreamError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EStreamError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EStreamError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EStreamError::~EStreamError

EStreamError

~EStreamError frees the memory associated with the EStreamError object.

__fastcall virtual ~EStreamError(void) { }

Description

Do not call ~EStreamError directly. Instead, use the delete keyword on the object, which causes ~EStreamError to be invoked automatically.


Hierarchy

TObject

Exception


EThread

Hierarchy	Properties	Methods	See also

EThread is the exception class for thread synchronization errors.

Unit

classes

Description

EThread is thrown when conflicts arise in multithreaded applications. This can occur if the Synchronize method of a thread is called before a previous call to it has completed execution.


EThread properties

EThread	Alphabetically

Derived from Exception

HelpContext

Message


EThread properties

EThread	By object

HelpContext

Message


EThread methods

EThread	Alphabetically

In EThread

~EThread

EThread

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EThread methods

EThread	By object

~EThread

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EThread

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EThread::EThread

EThread	See also

EThread creates a new EThread object.

__fastcall EThread(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EThread(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EThread(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EThread(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EThread(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EThread(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EThread(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EThread(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EThread instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EThread("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EThread::~EThread

EThread

~EThread frees the memory associated with the EThread object.

__fastcall virtual ~EThread(void) { }

Description

Do not call ~EThread directly. Instead, use the delete keyword on the object, which causes ~EThread to be invoked automatically.


Hierarchy

TObject

Exception


ETreeViewError

Hierarchy	Properties	Methods	See also

ETreeViewError is the exception class for unsuccessful attempts to access a tree view node.

Unit

comctrls

Description

ETreeViewError is thrown when an invalid index is requested from a TTreeView component.


ETreeViewError properties

ETreeViewError	Alphabetically

Derived from Exception

HelpContext

Message


ETreeViewError properties

ETreeViewError	By object

HelpContext

Message


ETreeViewError methods

ETreeViewError	Alphabetically

In ETreeViewError

~ETreeViewError

ETreeViewError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ETreeViewError methods

ETreeViewError	By object

~ETreeViewError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ETreeViewError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ETreeViewError::ETreeViewError

ETreeViewError	See also

ETreeViewError creates a new ETreeViewError object.

__fastcall ETreeViewError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall ETreeViewError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall ETreeViewError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall ETreeViewError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall ETreeViewError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall ETreeViewError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ETreeViewError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall ETreeViewError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

ETreeViewError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ETreeViewError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


ETreeViewError::~ETreeViewError

ETreeViewError

~ETreeViewError frees the memory associated with the ETreeViewError object.

__fastcall virtual ~ETreeViewError(void) { }

Description

Do not call ~ETreeViewError directly. Instead, use the delete keyword on the object, which causes ~ETreeViewError to be invoked automatically.


Hierarchy

TObject

Exception


ETreeViewError example

ETreeViewError


EUnderflow

Hierarchy	Properties	Methods	See also

EUnderflow is the exception class for values that are too small to be represented with a floating-point variable.

Unit

sysutils

Description

When a floating-point math operation produces a value that is too small to be represented in a floating-point variable, the result ordinarily becomes zero. However, an application can change the numeric coprocessor's control word to unmask underflow hardware exceptions; in this case, EUnderflow is thrown when the coprocessor reports an underflow hardware exception. The control word is reset after the exception.

As a descendant of EExternal, EUnderflow saves the Windows exception record (if there is one) in its ExceptionRecord data structure.


EUnderflow properties

EUnderflow	Alphabetically

Derived from Exception

HelpContext

Message


EUnderflow properties

EUnderflow	By object

HelpContext

Message


EUnderflow methods

EUnderflow	Alphabetically

In EUnderflow

~EUnderflow

EUnderflow

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EUnderflow methods

EUnderflow	By object

~EUnderflow

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EUnderflow

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EUnderflow::EUnderflow

EUnderflow	See also

EUnderflow creates a new EUnderflow object.

__fastcall EUnderflow(const System::AnsiString Msg) : Sysutils::EMathError(Msg) { }

__fastcall EUnderflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Msg, Args, Args_Size) { }

__fastcall EUnderflow(int Ident, Extended Dummy) : Sysutils::EMathError(Ident, Dummy) { }

__fastcall EUnderflow(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::EMathError(Ident, Args, Args_Size) { }

__fastcall EUnderflow(const System::AnsiString Msg, int AHelpContext) : Sysutils::EMathError(Msg, AHelpContext) { }

__fastcall EUnderflow(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EUnderflow(int Ident, int AHelpContext) : Sysutils::EMathError(Ident, AHelpContext) { }

__fastcall EUnderflow(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::EMathError(Ident, Args, Args_Size, AHelpContext) { }

Description

EUnderflow instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EUnderflow("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EUnderflow::~EUnderflow

EUnderflow

~EUnderflow frees the memory associated with the EUnderflow object.

__fastcall virtual ~EUnderflow(void) { }

Description

Do not call ~EUnderflow directly. Instead, use the delete keyword on the object, which causes ~EUnderflow to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EMathError


EUnderflow example

EUnderflow


EUpdateError

Hierarchy	Properties	Methods	See also

EUpdateError is the exception class for dataset provider update errors.

Unit

bdeprov

Description

EUpdateError is thrown if an error occurs when updates are being applied from a TProvider.


EUpdateError properties

EUpdateError	Alphabetically	Legend

In EUpdateError

Context

ErrorCode

PreviousError

Derived from Exception

HelpContext

Message


EUpdateError properties

EUpdateError	By object	Legend

Context

ErrorCode

HelpContext

Message

PreviousError


EUpdateError::Context

EUpdateError	See also

Contains context information from the error stack.

__property System::AnsiString Context = {read=FContext};

Description

Context contains additional information returned with the error message.


EUpdateError::ErrorCode

EUpdateError	See also

Indicates the error code returned by the BDE.

__property Word ErrorCode = {read=FErrorCode, nodefault};

Description

ErrorCode is the error code returned by the BDE.

DBIResult is a special integer type used by the DBIError procedure to hold BDE error codes.


EUpdateError::PreviousError

EUpdateError	See also

Indicates the previous error code returned by the BDE.

__property Word PreviousError = {read=FPreviousError, nodefault};

Description

PreviousError is the previous error code returned by the BDE.


EUpdateError methods

EUpdateError	Alphabetically

In EUpdateError

~EUpdateError

EUpdateError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EUpdateError methods

EUpdateError	By object

~EUpdateError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EUpdateError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EUpdateError::EUpdateError

EUpdateError	See also

Initializes an instance of EUpdateError using error information returned by the BDE.

__fastcall EUpdateError(System::AnsiString NativeError, System::AnsiString Context, Word ErrCode, Word PrevError);

__fastcall EUpdateError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Msg, Args, Args_Size) { }

__fastcall EUpdateError(int Ident, Extended Dummy) : Db::EDatabaseError(Ident, Dummy) { }

__fastcall EUpdateError(int Ident, const System::TVarRec * Args, const int Args_Size) : Db::EDatabaseError(Ident, Args, Args_Size) { }

__fastcall EUpdateError(const System::AnsiString Msg, int AHelpContext) : Db::EDatabaseError(Msg, AHelpContext) { }

__fastcall EUpdateError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EUpdateError(int Ident, int AHelpContext) : Db::EDatabaseError(Ident, AHelpContext) { }

__fastcall EUpdateError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Db::EDatabaseError(Ident, Args, Args_Size, AHelpContext) { }

Description

EUpdateError instantiates an EUpdateError object for a specified Borland Database Engine (BDE) error code and message string.

NativeError is the remote error code returned from the server.

Context is additional information to be returned with the error message.

ErrorCode is the error code returned by the BDE.

PrevError is the previous error code returned by the BDE.

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EUpdateError::~EUpdateError

EUpdateError	See also

~EUpdateError frees the memory associated with the EUpdateError object.

__fastcall virtual ~EUpdateError(void) { }

Description

Do not call ~EUpdateError directly. Instead, use the delete keyword on the object, which causes ~EUpdateError to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

Exception

EDatabaseError


EVariantError

Hierarchy	Properties	Methods	See also

EVariantError is the exception class for errors involving variant data types.

Unit

sysutils

Description

EVariantError is thrown when

•	An application attempts an invalid variant typecast or operation.

•	A variant does not contain a required OLE IDispatch object.

•	The VarArrayCreate function is unable to create a requested variant array.

•	A variant-array operation is attempted on something that is not a variant array.

•	A variant-array index is out of bounds.


EVariantError properties

EVariantError	Alphabetically

Derived from Exception

HelpContext

Message


EVariantError properties

EVariantError	By object

HelpContext

Message


EVariantError methods

EVariantError	Alphabetically

In EVariantError

~EVariantError

EVariantError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EVariantError methods

EVariantError	By object

~EVariantError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EVariantError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EVariantError::EVariantError

EVariantError	See also

EVariantError creates a new EVariantError object.

__fastcall EVariantError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EVariantError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EVariantError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EVariantError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EVariantError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EVariantError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EVariantError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EVariantError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EVariantError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EVariantError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EVariantError::~EVariantError

EVariantError

~EVariantError frees the memory associated with the EVariantError object.

__fastcall virtual ~EVariantError(void) { }

Description

Do not call ~EVariantError directly. Instead, use the delete keyword on the object, which causes ~EVariantError to be invoked automatically.


Hierarchy

TObject

Exception


TEvent

Hierarchy	Properties	Methods	See also

TEvent is a wrapper for a Windows event.

Unit

syncobjs

Description

Use TEvent to signal that an event has occurred or a state has been reached.

In a multi-threaded application, use TEvent to allow one thread to signal to other threads that an event has occurred.

The handle of a TEvent object can also be used to communicate with other processes, so that an application can coordinate the timing of events with other applications. For example, use the handle of a TEvent object to wait until another process is ready to transfer information through a Windows API call.

In a single-threaded application, use TEvent to coordinate between sections of code that respond to asynchronous events such as Windows messages.


TEvent properties

TEvent	Alphabetically	Legend

Derived from THandleObject

Handle

LastError


TEvent properties

TEvent	By object	Legend

Handle

LastError


TEvent methods

TEvent	Alphabetically

In TEvent

~TEvent

ResetEvent

SetEvent

TEvent

WaitFor

Derived from THandleObject

Derived from TSynchroObject

Acquire

Release

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TEvent methods

TEvent	By object

~TEvent

Acquire

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Release

ResetEvent

SafeCallException

SetEvent

TEvent

WaitFor


TEvent::TEvent

TEvent	See also

Instantiates a TEvent object to represent a Windows event object.

__fastcall TEvent(Windows::PSecurityAttributes EventAttributes, bool ManualReset, bool InitialState, const System::AnsiString Name);

Description

Call TEvent inderectly, using the new keyword, to create a TEvent object. TEvent can generate a new Windows event object or can provide access to an existing named event object.

Set the EventAttributes parameter to specify the access rights and inheritance capabilities of the new Windows event object. Calling TEvent with EventAttributes set to NULL creates an event object with a default set of security attributes. If the TEvent object is created to access an existing named event object, only the bInheritHandle field of EventAttributes is used, as the access rights were determined when the Windows event object was created.

Set ManualReset to specify whether the signal of the TEvent object can only be turned off by a call to the ResetEvent method, or whether it is automatically reset when a single waiting thread is released. When ManualReset is true, the TEvent signal stays set until the ResetEvent method turns it off. When ManualReset is false, the signal is automatically turned off when only a single thread waits on the signal and that thread is released. If the TEvent object is created to access an existing named event object, the ManualReset parameter is ignored.

Set InitialState to indicate whether the TEvent object should be created with the signal set, or turned off. When InitialState is true, the TEvent object is created with the signal set. If the TEvent object is created to access an existing named event object, the InitialState parameter is ignored.

Set Name to provide a name for a new Windows event object or to specify an existing named event object. If no other thread or process will need to access the event object to wait for its signal, Name can be left blank. Name can be a string of up to 260 characters, not including the backslash character (\). If Name is used to specify an existing event object, the value must match the name of the existing event in a case-sensitive comparison. If Name matches the name of an existing Windows semaphore, mutex, or file-mapping object, the TEvent object will be created with Handle set to 0 and all method calls will fail.


TEvent::ResetEvent

TEvent	See also

Turns off the signal of the event object.

void __fastcall ResetEvent(void);

Description

Call ResetEvent to signal that the event has not occurred or the desired state was not achieved. Other threads or processes that wait for the event will wait until the signal is turned on again by the SetEvent method, the event object is destroyed, or the waiting process times out.


TEvent::SetEvent

TEvent	See also

Turns on the signal of the event object.

void __fastcall SetEvent(void);

Description

Call SetEvent to signal that the event has occurred or the desired state was achieved. Other threads or processes that wait for the event will resume execution with a return value indicating that the signal was set.


TEvent::WaitFor

TEvent	See also

Waits until another thread or process turns on the signal of the event object.

enum TWaitResult { wrSignaled, wrTimeout, wrAbandoned, wrError };

TWaitResult __fastcall WaitFor(int Timeout);

Description

Call WaitFor to wait until the signal of the event object is turned on. If the signal is not set after Timeout milliseconds, WaitFor returns anyway. WaitFor returns one of the following values:

Value	Meaning

wrSignaled	The signal of the event object was set.

wrTimeout	The time specified by the Timeout parameter elapse without the signal being set.

wrAbandoned	The event object was destroyed before the Timeout period elapsed.

wrError	An error occurred while waiting. Check the LastError property for an error code giving more information.


TEvent::~TEvent

TEvent

~TEvent frees the memory associated with the TEvent object.

__fastcall virtual ~TEvent(void) { }

Description

Do not call ~TEvent directly. Instead, use the delete keyword on the object, which causes ~TEvent to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TSynchroObject

THandleObject


EWin32Error

Hierarchy	Properties	Methods	See also

EWin32Error is the exception class for Windows errors.

Unit

sysutils

Description

EWin32Error is thrown by the RaiseLastWin32Error procedure if Windows returns an error code. The exception dialog contains the error number and the message associated with the error.


EWin32Error properties

EWin32Error	Alphabetically

Derived from Exception

HelpContext

Message


EWin32Error properties

EWin32Error	By object

HelpContext

Message


EWin32Error methods

EWin32Error	Alphabetically

In EWin32Error

~EWin32Error

EWin32Error

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EWin32Error methods

EWin32Error	By object

~EWin32Error

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EWin32Error

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EWin32Error::EWin32Error

EWin32Error	See also

EWin32Error creates a new EWin32Error object.

__fastcall EWin32Error(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EWin32Error(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EWin32Error(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EWin32Error(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EWin32Error(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EWin32Error(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EWin32Error(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EWin32Error(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EWin32Error instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EWin32Error("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EWin32Error::~EWin32Error

EWin32Error	See also

~EWin32Error frees the memory associated with the EWin32Error object.

__fastcall virtual ~EWin32Error(void) { }

Description

Do not call ~EWin32Error directly. Instead, use the delete keyword on the object, which causes ~EWin32Error to be invoked automatically.


Hierarchy

TObject

Exception


EWriteError

Hierarchy	Properties	Methods	See also

EWriteError is the exception class for unsuccessful attempts to write data to a stream.

Unit

classes

Description

EWriteError is thrown when:

•	The WriteBuffer method of a stream object is unable to write the specified number of bytes.

•	The IDE is unable to write one of a component’s properties to a stream. This can occur when you try to save a form at design time.


EWriteError properties

EWriteError	Alphabetically

Derived from Exception

HelpContext

Message


EWriteError properties

EWriteError	By object

HelpContext

Message


EWriteError methods

EWriteError	Alphabetically

In EWriteError

~EWriteError

EWriteError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EWriteError methods

EWriteError	By object

~EWriteError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EWriteError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EWriteError::EWriteError

EWriteError	See also

EWriteError creates a new EWriteError object.

__fastcall EWriteError(const System::AnsiString Msg) : Classes::EFilerError(Msg) { }

__fastcall EWriteError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Msg, Args, Args_Size) { }

__fastcall EWriteError(int Ident, Extended Dummy) : Classes::EFilerError(Ident, Dummy) { }

__fastcall EWriteError(int Ident, const System::TVarRec * Args, const int Args_Size) : Classes::EFilerError(Ident, Args, Args_Size) { }

__fastcall EWriteError(const System::AnsiString Msg, int AHelpContext) : Classes::EFilerError(Msg, AHelpContext) { }

__fastcall EWriteError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EWriteError(int Ident, int AHelpContext) : Classes::EFilerError(Ident, AHelpContext) { }

__fastcall EWriteError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Classes::EFilerError(Ident, Args, Args_Size, AHelpContext) { }

Description

EWriteError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EWriteError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string or a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.

The Dummy parameter has no meaning.


EWriteError::~EWriteError

EWriteError

~EWriteError frees the memory associated with the EWriteError object.

__fastcall virtual ~EWriteError(void) { }

Description

Do not call ~EWriteError directly. Instead, use the delete keyword on the object, which causes ~EWriteError to be invoked automatically.


Hierarchy

TObject

Exception

EStreamError

EFilerError


Exception

Hierarchy	Properties	Methods

Exception is the base class for all runtime exceptions.

Unit

sysutils

Description

Exception encapsulates the fundamental properties and methods for all exceptions. Use Exception as the base class for creating custom exceptions.

All methods introduced for the Exception object are constructors that provide alternative ways to create exception messages. Some constructors also create help context IDs. Typically, an application calls these constructors dynamically when an exception occurs.

Exception messages can be hard-coded strings, formatted strings, or strings (including formatted strings ) loaded from an application resource.

Exceptions are raised when a runtime error occurs in an application, such as attempting to divide by zero. When an exception is raised, typically an exception instance displays a dialog box describing the error condition. If an application does not handle the exception condition, then the default exception handler is called. This handler also displays a dialog box with an OK button that usually permits an application to continue processing when the user clicks OK.

The Exception object provides a consistent interface for error conditions, and enables applications to handle error conditions in a graceful manner. Applications can

•	Trap for and handle specific exceptions in try..catch blocks.

•	Protect code that allocates resources from exception conditions by embedding the code in try..finally blocks (finally is a C++Builder language extension).

•	Throw exceptions or custom exceptions in response to program conditions.

Note

Standard practice is to name all derived exceptions beginning with “E”, followed by an abbreviated, descriptive name.


Exception properties

Exception	Alphabetically

In Exception

HelpContext

Message


Exception properties

Exception	By object

HelpContext

Message


Exception::HelpContext

Exception	See also

HelpContext contains the help-context ID number for context-sensitive online help associated with the exception.

__property int HelpContext = {read=FHelpContext, write=FHelpContext, nodefault};

Description

HelpContext provides storage for the help context ID number associated with the exception object. The context ID number determines the contents of the help screen that appears when a user presses F1 in response to an exception error message.

Note

Not all Exception constructors provide a value for HelpContext. To provide a help context for custom exceptions, use only the constructors listed below in the See also list.


Exception::Message

Exception	See also

Message contains the text string to display in the exception dialog box when the exception is raised.

__property System::AnsiString Message = {read=FMessage, write=FMessage};

Description

Message stores the error-message string to display when the exception is raised. All Exception constructors expect a string parameter to store in Message. Message text can be hard-coded as a parameter to an Exception constructor, created as dynamic parameter, or loaded from a resource file as a static or dynamically formatted parameter.


Exception methods

Exception	Alphabetically

In Exception

~Exception

Exception

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


Exception methods

Exception	By object

~Exception

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Exception

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


Exception::Exception

Exception	See also

Exception instantiates an instance of an exception with a simple message string.

__fastcall Exception(const System::AnsiString Msg);

__fastcall Exception(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size);

__fastcall Exception(int Ident);

__fastcall Exception(int Ident, const System::TVarRec * Args, const int Args_Size);

__fastcall Exception(const System::AnsiString Msg, int AHelpContext);

__fastcall Exception(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext);

__fastcall Exception(int Ident, int AHelpContext);

__fastcall Exception(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext);

Description

Exception instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw Exception("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, Exception creates an empty message string for the exception.


Exception::~Exception

Exception	See also

~Exception frees the memory associated with the Exception object.

__fastcall virtual ~Exception(void) { }

Description

Do not call ~Exception directly. Instead, use the delete keyword on the object, which causes ~Exception to be invoked automatically.


Hierarchy

TObject


Exception example

Exception


EZeroDivide

Hierarchy	Properties	Methods	See also

EZeroDivide is the exception class for floating-point divide-by-zero errors.

Unit

sysutils

Description

EZeroDivide exception is thrown when an application attempts to divide a floating-point value by zero.

As a descendant of EExternal, EZeroDivide saves the Windows exception record (if there is one) in its ExceptionRecord data structure.

Note

Integer divide-by-zero errors throw the EDivByZero exception.


EZeroDivide properties

EZeroDivide	Alphabetically

Derived from Exception

HelpContext

Message


EZeroDivide properties

EZeroDivide	By object

HelpContext

Message


EZeroDivide methods

EZeroDivide	Alphabetically

In EZeroDivide

~EZeroDivide

EZeroDivide

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EZeroDivide methods

EZeroDivide	By object

~EZeroDivide

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EZeroDivide

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EZeroDivide::EZeroDivide

EZeroDivide	See also

EZeroDivide creates a new EZeroDivide object.

Description


EZeroDivide::~EZeroDivide

EZeroDivide

~EZeroDivide frees the memory associated with the EZeroDivide object.

__fastcall virtual ~EZeroDivide(void) { }

Description

Do not call ~EZeroDivide directly. Instead, use the delete keyword on the object, which causes ~EZeroDivide to be invoked automatically.


Hierarchy

TObject

Exception

EExternal

EMathError


EZeroDivide example

EZeroDivide


TField

Hierarchy	Properties	Methods	Events	See also

TField is the common ancestor of all the field components in a dataset.

Unit

db

Description

TField encapsulates the fundamental behavior common to all field components. It introduces the properties, events, and methods that are used to:

•	Change the value of a field in a dataset.

•	Convert the value of a field from one data type to another.

•	Validate data that the user enters for a field.

•	Define how the data in the field appears as it is displayed or edited.

•	Calculate the value of a field from code written in the OnCalcFields event of the dataset.

•	Look up the field’s value from another dataset.

Do not create instances of TField. TField descendants are created automatically each time a dataset is activated. These descendants can be dynamic (the default) or persistent. Dynamic field components reflect the actual columns of the underlying physical table at the time a dataset is opened. Persistent field components are created at design time using the Fields editor, which specifies the fields in the dataset, their properties, and their ordering.

Creating persistent field components guarantees that each time an application runs, it uses and displays the same columns, in the same order, even if the physical structure of the underlying database changes. If a column on which a persistent field component is based is deleted or changed, C++Builder generates an exception rather than opening the table against a nonexistent column or mismatched data. If this happens, remove the field component for the nonexistent field using the Fields editor.

A field in a dataset is always one of the following TField descendants:

TStringField	TBlobField	TTimeField
TSmallintField	TIntegerField	TBytesField
TFloatField	TWordField	TVarBytesField
TCurrencyField	TAutoIncField	TGraphicField
TBooleanField	TBCDField	TMemoField
TDateField	TDateTimeField


TField properties

TField	Alphabetically	Legend

In TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Value

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TField properties

TField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TField::Alignment

TField	See also

Determines how the field’s data is displayed within a data-aware control.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

Use Alignment to specify the position of the field’s data within data-aware controls. These are the possible values:

Value	Meaning

taLeftJustify	Align data to the left side of the control

taCenter	Center data horizontally in the control

taRightJustify	Align data to the right side of the control


TField::AsBoolean

TField	See also

Represents the field’s value as a boolean value.

__property bool AsBoolean = {read=GetAsBoolean, write=SetAsBoolean, nodefault};

Description

AsBoolean provides a property to read the value of the field’s data into a boolean, or to assign a Boolean value to the contents of the field. TField does not support boolean values, and throws an exception whenever an attempt is made to get or set the AsBoolean property.

Descendants of TField that represent boolean fields or that support conversions between the field’s Value property and a boolean value, override AsBoolean to read and write the value of the field as a boolean value.


TField::AsCurrency

TField	See also

Represents the field’s value as a Currency value.

__property System::Currency AsCurrency = {read=GetAsCurrency, write=SetAsCurrency};

Description

AsCurrency provides a property to read the value of the field’s data into an object or variable of type Currency, or to assign a Currency value to the contents of the field. TField does not support Currency values, and throws an exception whenever an attempt is made to get or set the AsCurrency property.

Descendants of TField that represent currency fields or that support conversions between the field’s Value property and a Currency value, override AsCurrency to read and write the value of the field as a Currency value.


TField::AsDateTime

TField	See also 	Example

Represents the field’s value as a TDateTime value.

__property System::TDateTime AsDateTime = {read=GetAsDateTime, write=SetAsDateTime};

Description

AsDateTime provides a property to read the value of the field’s data into an object or variable of type TDateTime, or to assign a TDateTime value to the contents of the field. TField does not support TDateTime values, and throws an exception whenever an attempt is made to get or set the AsDateTime property.

Descendants of TField that represent datetime (timestamp) fields or that support conversions between the field’s Value property and a TDateTime value, override AsDateTime to read and write the value of the field as a TDateTime value.


TField::AsFloat

TField	See also

Represents the field’s value as a double value.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

AsFloat provides a property to read the value of the field’s data into a double, or to assign a Double value to the contents of the field. TField does not support floating point values, and throws an exception whenever an attempt is made to get or set the AsFloat property.

Descendants of TField that represent floating point numeric fields or that support conversions between the field’s Value property and a double value, override AsFloat to read and write the value of the field as a double value.


TField::AsInteger

TField	See also 	Example

Represents the field’s value as a 32-bit integer.

__property int AsInteger = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

AsInteger provides a property to read the value of the field’s data into an integer, or to assign an integer value to the contents of the field. TField does not support integer values, and throws an exception whenever an attempt is made to get or set the AsInteger property.

Descendants of TField that represent integer fields or that support conversions between the field’s Value property and an integer value, override AsInteger to read and write the value of the field as an integer value.


TField::AsString

TField	See also 	Example

Represents the field’s value as an AnsiString.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Reading the AsString property returns the abbreviated class name of the field component enclosed in parentheses. The abbreviated class name is built by stripping the leading ‘T’ from the class name and removing the trailing word ‘FIELD’, except in the case of TField where that would leave an empty string. Thus, the abbreviated class name of TField is “FIELD”, the abbreviated class name of TVarBytesField is “VarBytes”, and so on.

Trying to set the AsString property throws an exception.

Descendants of TField that represent string fields or that support conversions between the field’s Value property and a string override AsString to read and write the value of the field as a different, more meaningful, string.


TField::AsVariant

TField	See also

Represents the Value of the field as type Variant.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

AsVariant provides a property to read the value of the field’s data into a Variant, or to assign a Variant value to the contents of the field. TField does not support Variant values, and throws an exception when an attempt is made to read the AsVariant property. TField also throws an exception when an attempt is made to set the AsVariant property, unless the Variant is of type varNull, in which case TField calls the Clear method.

Descendants of TField implement the AsVariant method to get or set the value of the field as a Variant.


TField::AttributeSet

TField	See also

Specifies the name of an attribute set in the data dictionary to apply to the field component.

__property System::AnsiString AttributeSet = {read=FAttributeSet, write=FAttributeSet};

Description

An attribute set defines the display and format properties of a field component that are displayed in a data-aware control at design time. It also defines any constraint and default properties of the field component.

Attribute sets are stored in the data dictionary by name so that at design time developers can create and apply the same set of attributes to different field components in one or more datasets. When an attribute set is assigned to a field component at design time and that field component is owned by a TQuery or TStoredProc dataset, AttributeSet contains the name of the assigned attribute set.


TField::Calculated

TField	See also

Determines whether the value of the field is calculated by the OnCalcFields event handler of its dataset.

__property bool Calculated = {read=GetCalculated, write=SetCalculated, default=0};

Description

Use Calculated to determine if the field is a calculated field. When Calculated is true and the OnCalcFields event occurs, the OnCalcFields event handler updates the value of the field. The default value is false.

The value of a Calculated field is not stored in or retrieved from the physical tables underlying a dataset. Instead, calculated fields are calculated for each record in the table by the dataset's OnCalcFields event handler, which typically uses expressions involving values from other fields in the record to generate a value for each calculated field.

For example, a table might have non-calculated fields for Quantity and UnitPrice, and a calculated field for ExtendedPrice, which would be calculated by multiplying the values of the Quantity and UnitPrice fields in an OnCalcFields event handler.

Note:	Do not change the setting of Calculated in application code. Calculated is automatically set to true by the Fields editor at design time if a field’s value is specified as calculated.

Note:	Do not confuse the Calculated property with the InternalCalcField property of a field definition. The value of a calculated field is computed in the OnCalcFields event handler. The value of an internally calculated field is computed by the SQL server or the Borland Database engine.


TField::CanModify

TField	See also

Specifies whether a field can be modified.

__property bool CanModify = {read=GetCanModify, nodefault};

Description

Check CanModify to determine if a field’s data can be edited. CanModify is true only if the ReadOnly property is false, and the dataset for this field component allows write access to the corresponding database field.


TField::ConstraintErrorMessage

TField	See also

Specifies a customized error message that appears when the user tries to set a value that violates the data constraints of the field.

__property System::AnsiString ConstraintErrorMessage = {read=FConstraintErrorMessage, write=FConstraintErrorMessage};

Description

Set ConstraintErrorMessage to specify the message that appears when the user-supplied value for the field does not meet the constraints imposed by the server or specified in the CustomConstraint property.


TField::CurValue

TField	See also

Represents the current value of the field component including changes made by other users of the database.

__property System::Variant CurValue = {read=GetCurValue};

Description

Use CurValue to examine the value of a field when a problem occurs in posting a value to the database using a TProvider. If the current field value is causing a problem (such as a key violation) when posting the value, an event is generated to allow applications to respond to the problem. Client datasets generate an OnReconcileError event. On the server side, provider objects generate an OnUpdateError event. In the event handler, NewValue is the unposted value that caused the problem, OldValue is the value that was originally assigned to the field before any edits were made, and CurValue is the value that is currently assigned to the field. CurValue may differ from OldValue if another user changed the value of the field after OldValue was read.

Note:	CurValue is only supported when the dataset is a TClientDataSet. In the TProvider::OnUpdateError event, a temporary client dataset containing fields with a CurValue property is passed to the event handler.


TField::CustomConstraint

TField	See also

Specifies an SQL string the enforces any application-specific constraints on the field’s value.

__property System::AnsiString CustomConstraint = {read=FCustomConstraint, write=FCustomConstraint};

Description

Set CustomConstraint to limit the values that the user can enter into a field. CustomConstraint must be a valid SQL search expression such as

x > 0 and x < 100

The name used to refer to the value of the field can be any string that is not a reserved SQL keyword, as long as it is used consistently throughout the constraint expression.

Custom constraints are imposed in addition to any constraints to the field’s value that come from the server. To see the constraints imposed by the server, read the ImportedConstraint property.

Note:	When setting the CustomConstraint property, be sure to set the ConstraintErrorMessage property as well, so that a message will appear to the user when a value is entered that violates the custom constraint.


TField::DataSet

TField	See also

Identifies the dataset to which a field component belongs.

__property TDataSet* DataSet = {read=FDataSet, write=SetDataSet, stored=false};

Description

Check the value of the DataSet property to determine the dataset that uses the field component to represent one of its fields. Applications should not directly assign the DataSet property of a field. It is assigned automatically when the field is created from a TFieldDef object.


TField::DataSize

TField	See also 	Example

Indicates the amount of memory needed to store a field component’s value.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a field component’s value. Use DataSize to determine the required size of a buffer for working with the field’s value in native format. For example, use DataSize to determine the buffer size needed by the GetData and SetData methods.

The value of DataSize for TField is 0. Most descendants of TField override this property to specify the size required by the specific field type they represent. BLOB fields, however, represent data of indeterminate size. They do not override the inherited method, and the value of DataSize for BLOB fields is 0. A value of zero should not be interpreted as meaning the field value requires no memory. A value of zero indicates that the memory required for the field is indeterminate.


TField::DataType

TField	See also

Identifies the data type of the field component.

enum TFieldType { ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat, ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc, ftBlob, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary, ftCursor };

__property TFieldType DataType = {read=FDataType, nodefault};

Description

Read the DataType property to learn the type of the data the field contains. The DataType property is equal to one of the following values:

Value	Description

ftUnknown	Unknown or undetermined

ftString	Character or string field

ftSmallint	16-bit integer field

ftInteger	32-bit integer field

ftWord	16-bit unsigned integer field

ftBoolean	Boolean field

ftFloat	Floating-point numeric field

ftCurrency	Money field

ftBCD	Binary-coded Decimal field

ftDate	Date field

ftTime	Time field

ftDateTime	Date and time field

ftBytes	Fixed number of bytes (binary storage)

ffVarBytes	Variable number of bytes (binary storage)

ftAutoInc	Auto-incrementing 32-bit integer counter field

ftBlob	Binary Large OBject field

ftMemo	Text memo field

ftGraphic	Bitmap field

ftFmtMemo	Formatted text memo field

ftParadoxOle	Paradox OLE field

ftDBaseOle	dBASE OLE field

ftTypedBinary	Typed binary field

ftCursor	Does not apply to field components.


TField::DefaultExpression

TField	See also

Specifies an SQL expression that is assigned to the field if the user does not provide a value.

__property System::AnsiString DefaultExpression = {read=FDefaultExpression, write=FDefaultExpression};

Description

Set DefaultExpression to provide a default value for a field. DefaultExpression can be any valid SQL value expression that does not refer to field values. If the expression contains literals other than numeric values, they must appear in quotes. For example, a default value of noon for a time field would be

'12:00:00'

including the quotes around the literal value.


TField::DisplayLabel

TField	See also 	Example

Contains the text to display in the corresponding column heading of a data grid.

__property System::AnsiString DisplayLabel = {read=GetDisplayLabel, write=SetDisplayLabel, stored=IsDisplayLabelStored};

Description

Use DisplayLabel to assign column headings to a data grid. The column headings of the data grid use the DisplayName property of the field whose value they represent. Setting DisplayLabel changes DisplayName property from FieldName to the string specified as DisplayLabel.


TField::DisplayName

TField	See also

Represents the name of the field for display purposes.

__property System::AnsiString DisplayName = {read=GetDisplayName};

Description

Use DisplayName when displaying a string that represents the field to the user. For example, when raising an exception concerning the field, format an error string that includes the DisplayName to refer to the field. DisplayName is a read-only property. To change the value of DisplayName, use the DisplayLabel property.

If DisplayLabel is defined, DisplayName is the same as DisplayLabel. Otherwise, DisplayName is the same as the FieldName property.


TField::DisplayText

TField	See also

Represents the field’s value as it is displayed in a data-aware control.

__property System::AnsiString DisplayText = {read=GetDisplayText};

Description

DisplayText is a read-only string representation of a field’s value to display in a data-aware control. If an OnGetText event handler is assigned, DisplayText is the value returned in the Text parameter of the OnGetText event handler when the DisplayText parameter is true. Otherwise, DisplayText is the value of the AsString property.

DisplayText is the string representation of the field’s Value property when it is not being edited. When the field is being edited, use the Text property.


TField::DisplayWidth

TField	See also

Specifies the number of characters that should be used to display a field’s value by a cooperating data-aware control.

__property int DisplayWidth = {read=GetDisplayWidth, write=SetDisplayWidth, stored=IsDisplayWidthStored, nodefault};

Description

Set DisplayWidth to control how many characters are used to calculate the column width for the field when it is displayed by a TDBLookupListBox object or a descendant if TCustomDBGrid. The actual width of columns is determined by the average character width. If the data-aware control that displays the field is not using a fixed pitch font, DisplayWidth may indicate more or fewer characters than will fit in the column for any given string.

Note:	The DisplayWidth property has no effect if there is an explicit Columns value for the field in a TDBGrid object.


TField::EditMask

TField	See also

Contains the mask that is used to restrict the data that can be entered into a data field.

__property System::AnsiString EditMask = {read=FEditMask, write=SetEditMask};

Description

Use EditMask to restrict the characters the user can enter to valid characters and formats. If the user attempts to enter a character that is not valid, the character is not accepted. Validation using the EditMask property is performed on a character-by-character basis. Use an OnValidate event to validate the entire input, just before it is posted to the database.

A mask consists of three fields with semicolons separating the fields. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are included as part of the data. The third part of the mask is the character used to represent unentered characters in the mask.

These are the special characters used in the first field of the mask:

Character	Meaning in mask

     !	If a ! character appears in the mask, optional characters are represented in the EditText as leading blanks. If a ! character is not present, optional characters are represented in the EditText as trailing blanks.

     >	If a > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a < character is encountered.

     <	If a < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a > character is encountered.

     <>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data.

     \	The character that follows a \ character is a literal character. Use this character when you want to allow any of the mask special characters as a literal in the data.

     L	The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.

     l	The l character permits only an alphabetic character in this position, but doesn't require it.

     A	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.

     a	The a character permits an alphanumeric character in this position, but doesn't require it.

     C	The C character requires an arbitrary character in this position.

     c	The c character permits an arbitrary character in this position, but doesn't require it.

     0	The 0 character requires a numeric character only in this position.

     9	The 9 character permits a numeric character in this position, but doesn't require it.

     #	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.

    :	The : character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel utility on your computer system, that character is used instead of :.

     /	The / character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the regional settings of the Control Panel utility on your computer system, that character is used instead of /.

    ;	The ; character is used to separate the three fields of the mask.

     _	the _ character automatically inserts spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters must be matched exactly when entering data for the field. They are inserted automatically, and the cursor skips over them during editing. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the Value property of the field. For example, the mask for a telephone number with area code could be the following string:

The 0 in the second field indicates that the Value property for the field would consist of the 10 digits that were entered, rather than the 14 characters that make up the telephone number as it appears to the user.

A 0 in the second field indicates that literals should not be included, any other character indicates that they should be included. The character to indicate whether literals should be included can be changed in the EditMask property editor, or programmatically by changing the MaskNoSave typed constant defined in the Mask unit.

The third field of the mask is the character that appears in the edit control for blanks (characters that have not been entered). By default, this is the same as the character that stands for literal spaces. The two characters appear the same in an edit window. However, when a user enters the data for the field, the cursor selects each blank character in turn, and skips over the space character.

Setting EditMask to an empty string removes the mask.

Note:	When working with multibyte character sets, such as Japanese shift-JIS, each special mask character represents a single byte. To specify double-byte characters using the L,l,A,a,C, or c specifiers, the mask characters must be doubled as well. For example, LL would represent two single-byte alphabetic characters or a one double-byte character. Only single-byte literal characters are supported.


TField::EditMaskPtr

TField	See also

Provides read-only access to the EditMask property.

__property System::AnsiString EditMaskPtr = {read=FEditMask};

Description

Use EditMaskPtr when reading the EditMask property. Because EditMaskPtr is a read-only property, EditMaskPtr guards against accidentally changing the value of the mask in code that should only read it.


TField::FieldKind

TField	See also

Indicates whether a field represents a column in a dataset, a calculated field, or a lookup field.

enum TFieldKind { fkData, fkCalculated, fkLookup, fkInternalCalc };

__property TFieldKind FieldKind = {read=FFieldKind, write=SetFieldKind, stored=FieldKindStored, nodefault};

Description

Use FieldKind to determine if a field is a data field, a calculated field, or a lookup field. The value of FieldKind can be changed programmatically, but in practice FieldKind is set at design time when creating Field components with the Fields editor.

The FieldKind property can take one of the following values:

Value	Description

fkData	Field represents a physical field in a database table

fkCalculated	Field is calculated in an OnCalcFields event handler

fkLookup	Field is a lookup field

fkInternalCalc	Field is calculated but values are stored in the dataset.

Note:	Fields calculated by SQL servers or the Borland Database Engine to display the results of a query that returns a live dataset have a FieldKind of fkInternalCalc, not fkCalculated. This is because the field values are stored in the dataset. Calculated fields in a client dataset are calculated in an OnCalcFields event handler, but stored internally in the dataset. They also have a FieldKind of fkInternalCalc instead of fkCalculated. Unlike regular calculated fields, these fields can be used in filter expressions. They can also edited, but the changes are discarded. To prevent editing, set the ReadOnly property to true.

Note:	The FieldKind property of a field is only stored with the field object if the value is fkInternalCalc.


TField::FieldName

TField	See also 	Example

Indicates the name of the physical column in the underlying dataset to which a field component is bound.

__property System::AnsiString FieldName = {read=FFieldName, write=SetFieldName};

Description

When creating a field component, the TFieldDef object uses FieldName to specify which field in underlying dataset the field component represents. FieldName is used when displaying references to the field to users, unless a DisplayLabel has been set. For calculated fields, supply a FieldName when defining the field. For non-calculated fields, an EDatabaseError exception is thrown if a FieldName is not a column name in the physical table.


TField::FieldNo

TField	See also

Specifies the ordinal of the field component’s column in the physical table underlying a dataset.

__property int FieldNo = {read=FFieldNo, nodefault};

Description

Read FieldNo to learn a field component’s ordinal position in the table underlying the dataset, where 1 is the first field. Use the FieldNo property to specify the field only in direct API calls to the Borland Database Engine.

Note:	Don’t confuse FieldNo, which is the field component’s ordinal position in the physical database table, with Index, the field components position in the dataset’s Fields property.


TField::HasConstraints

TField	See also

Indicates whether field values are constrained.

__property bool HasConstraints = {read=GetHasConstraints, nodefault};

Description

Read HasConstraints to determine whether the field component imposes custom constraints, imported constraints, or a default expression. HasConstraints is true if the CustomConstraint, DefaultExpression, or ImportedConstraint property is set. Otherwise, HasConstraints is false, indicating that the server or database engine are not imposing any constraints on field values.

Field values can still be limited when HasConstraints is false. For example, an edit mask or OnValidate event handler can constrain field values. However, these constraints are imposed by the C++Builder application, not by the server or database engine.


TField::ImportedConstraint

TField	See also

Represents an SQL clause that enforces constraints stored on the server.

__property System::AnsiString ImportedConstraint = {read=FImportedConstraint, write=FImportedConstraint};

Description

Read ImportedConstraint to determine the limits imposed by the server on what values are valid for the field. ImportedConstraint is an SQL search expression such as

Value > 0 and Value < 100

Do not change the value of ImportedConstraint. To add additional constraints on the field value, use the CustomConstraint property instead. Custom constraints are imposed in addition to the imported constraints. If the server constraints change, the value of ImportedConstraint will be changed but constraints introduced in the CustomConstraint property will persist.

Removing constraints from the ImportedConstraint property will not change the validity of field values that violate those constraints. Removing constraints will result in the constraints being checked by the server instead of locally. When constraints are checked locally, the error message supplied as the ConstraintErrorMessage property is displayed when violations are found, instead of an error message from the server.


TField::Index

TField	See also

Specifies the field component’s index number into the Fields property of the dataset.

__property int Index = {read=GetIndex, write=SetIndex, stored=false, nodefault};

Description

Use the Index property to:

•	Find the position of the field in the dataset.

•	Change the order of a field's position in the dataset by changing the value of Index. Changing the Index value affects the order in which fields are displayed in data grids, but not the position of the fields in the physical database tables.

Note:	The field order can also be changed by dragging and dropping fields in the Fields editor at design time.


TField::IsIndexField

TField	See also

Specifies whether a field is an index field.

__property bool IsIndexField = {read=GetIsIndexField, nodefault};

Description

Use the IsIndexField to determine if a field is an index field. If IsIndex is true, a field is one of the fields that makes up the index on the underlying database table. If IsIndexField is false, the field is not an index field. A field component must be an index field to serve as one of the field components for the LookupKeyFields in a lookup table.


TField::IsNull

TField	See also

Indicates whether the field has a value assigned to it.

__property bool IsNull = {read=GetIsNull, nodefault};

Description

Use IsNull to determine if the field contains a value. If IsNull is true, the field is blank. If IsNull is false, the field has a value.


TField::KeyFields

TField	See also

Identifies the field or fields in the dataset that must be matched in the lookup dataset when doing a lookup.

__property System::AnsiString KeyFields = {read=FKeyFields, write=SetKeyFields};

Description

Set KeyFields only on lookup fields (fields where FieldKind is fkLookup and Lookup is true). KeyFields specifies the field or fields to match when a lookup occurs. To use more than one field, separate each field name with a semicolon. The specified fields must be of the same types as the corresponding fields in LookupKeyFields, or the lookup fails.

The values of the KeyFields in the DataSet are matched with the values of the LookupKeyFields in the LookupDataSet to determine a particular record of the lookup table. The value of the LookupResultField on that record becomes the Value property for the field component.


TField::Lookup

TField	See also

Determines whether the field is specified as a lookup field.

__property bool Lookup = {read=GetLookup, write=SetLookup, nodefault};

Description

Lookup is provided for backward compatibility. To determine if a field is a lookup field, use the FieldKind property instead.

If the field is a lookup field, the KeyFields property indicates which fields in the dataset must match the LookupKeyFields in the LookupDataSet, to identify a record in the LookupDataSet. The value of the LookupResultField for that record becomes the Value of the field component.


TField::LookupCache

TField	See also

Determines whether the values of a lookup field are cached or looked up dynamically every time the current record in the dataset changes.

__property bool LookupCache = {read=FLookupCache, write=SetLookupCache, default=0};

Description

Set LookupCache to true to cache the values of a lookup field when the LookupDataSet is unlikely to change and the number of distinct lookup values is small. Caching lookup values can speed performance, because the lookup values for every set of LookupKeyFields values are preloaded when the DataSet is opened. When the current record in the DataSet changes, the field object can locate its Value in the cache, rather than accessing the LookupDataSet. This performance improvement is especially dramatic if the LookupDataSet is on a network where access is slow.

If every record of DataSet has different values for KeyFields, the overhead of locating values in the cache can be greater than any performance benefit provided by the cache. The overhead of locating values in the cache increases with the number of distinct values that can be taken by KeyFields.

If LookupDataSet is volatile, caching lookup values can lead to inaccurate results. Call RefreshLookupList to update the values in the lookup cache. RefreshLookupList regenerates the LookupList property, which contains the value of the LookupResultField for every set of LookupKeyFields values.

When setting LookupCache at runtime, call RefreshLookupList to initialize the cache.

Note:	LookupCache is only meaningful if the value of FieldKind is fkLookup.


TField::LookupDataSet

TField	See also

Identifies the dataset used to look up field values.

__property TDataSet* LookupDataSet = {read=FLookupDataSet, write=SetLookupDataSet};

Description

Use LookupDataSet to specify the dataset to use for looking up field values in a field with a FieldKind of fkLookup.

When a field component is a lookup field, the Value of the field component is the value of the LookupResultField in the LookupDataSet. The record in the LookupDataSet that contains the correct value is found by matching the LookupKeyFields in the LookupDataSet with the current values of the KeyFields in the DataSet.


TField::LookupKeyFields

TField	See also

Identifies the field or fields in the lookup dataset to match when doing a lookup.

__property System::AnsiString LookupKeyFields = {read=FLookupKeyFields, write=SetLookupKeyFields};

Description

Only use LookupKeyFields on field components with a FieldKind of fkLookup. LookupKeyFields are the fields in the index of the LookupDataSet whose values must match the KeyFields in the field component’s DataSet.

To specify more than one field, separate each field name with a semicolon. The fields specified in LookupKeyFields must be of the same types as the corresponding fields in KeyFields, or the lookup can't work.

Matching the values of the LookupKeyFields in the LookupDataSet with the values of the KeyFields in the DataSet determines a specific record in the LookupDataSet. The Value of the field component is the value of the LookupResultField in the indicated record.


TField::LookupList

TField	See also

Specifies a cache of values from the LookupDataSet indexed by a set of values from the KeyFields property.

__property TLookupList* LookupList = {read=GetLookupList};

Description

Use LookupList to find the cached value assigned to the field for a given set of values on the fields specified by KeyFields. The value of LookupList is set when the dataset is open or the RefreshLookupList method is called. Applications can also set the LookupList programmatically to provide lookup values when the lookup dataset does not actually exist.

The ValueOfKey method of the LookupList returns the value of the LookupResultField for a set of values on the LookupKeyFields. This allows the value of the lookup field object to be computed as follows:

Value = LookupList->ValueOfKey(DataSet->FieldValues[KeyFields]);

Note:	LookupList is only meaningful when the value of FieldKind is fkLookpup and the LookupCache property is true.


TField::LookupResultField

TField	See also

Identifies the field from the lookup dataset whose value becomes the Value property of the field component.

__property System::AnsiString LookupResultField = {read=FLookupResultField, write=SetLookupResultField};

Description

Use LookupResultField to specify a single field in the LookupDataSet whose value becomes the value of the field component. The field component must have a FieldKind of fkLookup, and the DataType of the field component must be the same as the data type of the LookupResultField.

When a field component is a lookup field, the Value of the field component is the value of the LookupResultField in the LookupDataSet. The record in the LookupDataSet that contains the correct value is found by matching the LookupKeyFields in the LookupDataSet with the current values of the KeyFields in the DataSet.


TField::NewValue

TField	See also

Represents the current value of the field component including pending cached updates.

__property System::Variant NewValue = {read=GetNewValue, write=SetNewValue};

Description

Use NewValue to examine or change the current value to a field when in the process of posting multiple records. If the current field value is causing a problem, such as a key violation, when applying a cached update, datasets generate an OnUpdateError event. Similarly, TProvider objects generate an OnUpdateError event when problems occur posting records from a client, and client datasets generate an OnReconcileError event when informed of problems by the server. In the event handler, assign a new value to NewValue to correct the problem.

NewValue is the same as Value, except when errors are encountered while posting records. Setting NewValue in an OnUpdateError event handler, an OnUpdateRecord event handler, or an OnReconcileError event handler will cause NewValue to differ from Value until the records have finished being posted to the underlying database table.


TField::Offset

TField	See also

Indicates the number of bytes added to the end of the current record buffer in the dataset for storing cached values (for calculated fields or BLOB fields).

__property Word Offset = {read=FOffset, nodefault};

Description

Read Offset to determine the extra space in the record buffer of a TClientDataSet object allocated for cached information on calculated fields or BLOB fields. Offset should only be used by component writers when developing new descendants of TClientDataSet.


TField::OldValue

TField	See also

Represents the original value of the field (as a Variant).

__property System::Variant OldValue = {read=GetOldValue};

Description

Read the OldValue property to examine or retrieve the original value of the field that was obtained from the dataset before any new values were written to the record buffer. For example, this code replaces current pending changes with a field’s original value:

NewValue = OldValue;

Once records are posted successfully, the old field value cannot be retrieved.


TField::Origin

TField	See also

Indicates the name of the field in its original dataset.

__property System::AnsiString Origin = {read=FOrigin, write=FOrigin};

Description

Use the Origin property to distinguish the name of the field as it appears in its dataset from the name of the field on which it is based. For example, in a query that uses the following SQL statement, the value of Origin is CUSTOMER.CUSTNO.

SELECT CUSTNO AS ID FROM CUSTOMER

In this case, the FieldName property is ID.

Origin is especially useful when working with multi-table joins, as it distinguishes which table the field came from.

Note:	Origin is only assigned at design time by the Fields editor, and only when the field component is used by a TQuery object.


TField::ReadOnly

TField	See also

Determines whether the field can be modified.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, default=0};

Description

Set ReadOnly to true to prevent a field from being modified. In a data grid, tabbing from field to field skips over ReadOnly fields.

To learn whether a field can be modified, use the CanModify property instead. CanModify reflects not only the value of the ReadOnly property, but also any restrictions imposed by the underlying dataset.


TField::Required

TField	See also

Specifies whether a nonblank value for a field is required.

__property bool Required = {read=FRequired, write=FRequired, default=0};

Description

Use Required to find out if a field requires a value or if the field can be blank.

If a field is created with the Fields editor, then this property is set based on the underlying table. Applications that set Required to true for fields that must have values (for example, a password or part number), but for which the underlying table does not require the field, must write an OnValidate event handler to enforce the property.

When the Required property reflects a property of the underlying database table, trying to post a null value will cause an exception to be raised. Applications that set the Required property to true when the underlying table does not require the field, should throw an exception on null values in the OnValidate event handler in order to achieve the same result.


TField::Size

TField	See also

Indicates the size used in the definition of the physical database field for data types that support different sizes.

__property Word Size = {read=FSize, write=SetSize, nodefault};

Description

The interpretation of Size depends on the data type. Size is the size associated with the field by the Borland DataBase Engine. The meaning of Size for different data types is given in the following table:

DataType	Meaning of Size

ftBoolean	Size is not used; its value is always 0.

ftSmallInt	Size is not used; its value is always 0.

ftWord	Size is not used; its value is always 0.

ftAutoInc	Size is not used; its value is always 0.

ftDate	Size is not used; its value is always 0.

ftInteger	Size is not used; its value is always 0.

ftTime	Size is not used; its value is always 0.

ftCurrency	Size is not used; its value is always 0.

ftDateTime	Size is not used; its value is always 0.

ftFloat	Size is not used; its value is always 0.

ftBCD	Size is the number of digits after the decimal place.

ftString	Size is the maximum number of characters in the string.

ftVarBytes	Size is the maximum number of bytes of data, not counting the first two bytes which indicate the actual number of bytes of data that were used.

ftBytes	Size is the maximum number of bytes of data.

ftBlob	Size is the number of bytes from the BLOB that are stored in the record buffer.

ftDBaseOle	Size is the number of bytes from the DBase OLE BLOB that are stored in the record buffer.

ftFmtMemo	Size is the number of bytes from the memo that are stored in the record buffer.

ftGraphic	Size is the number of bytes from the image that are stored in the record buffer.

ftMemo	Size is the number of characters from the memo that are stored in the record buffer.

ftParadoxOle	Size is the number of bytes from the Paradox OLE BLOB that are stored in the record buffer.

ftTypedBinary	Size is the number of bytes from the BLOB that are stored in the record buffer.

ftUnknown	Size is not used; its value is always 0.

ftCursor	Size is not used; its value is always 0.


TField::Text

TField	See also

Contains the string to display in a data-aware control when the field is in edit mode.

__property System::AnsiString Text = {read=GetEditText, write=SetEditText};

Description

Data-aware controls rely on the Text property to provide the editing format for each field. For example, by default the Text property of a currency field omits the thousands separators and currency symbol.

Text can differ from the DisplayText property if the field should have a different string representation when the value is being edited. To implement two different string representations of a field’s value, use the OnGetText event handler. If an OnGetText event handler is assigned, Text is the value returned in the Text parameter of the OnGetText event handler when the DisplayText parameter is false. Otherwise, Text is the value of the AsString property.


TField::ValidChars

TField	See also

Specifies the characters that can be included in the text representation of the field’s value.

typedef Set<char, 0, 255> TFieldChars;

__property TFieldChars ValidChars = {read=FValidChars, write=FValidChars};

Description

Set ValidChars to restrict the characters that can be validly entered as part of the text representation of the field’s value. ValidChars is used by the IsValidChar method to determine whether a character typed into a data-aware edit control can make up part of the field’s value. Unlike the EditMask property which specifies which characters can appear in specific positions, ValidChars limits the characters that can appear anywhere in the field’s value.

TField initializes ValidChars to include all characters. Numeric descendants of TField change the default value to include only the characters that can make up a numeric value. Applications can change this value to restrict the character set for a field in other ways or to allow characters that are not permitted by default.


TField::Value

TField	See also 	Example

Represents the data in a field component.

__property System::Variant Value = {read=GetAsVariant, write=SetAsVariant};

Description

Use Value to read data directly from and write data directly to a field component at runtime. For example, use the Value property to affect the contents of a field that is not Visible.


TField::Visible

TField	See also

Determines whether the field appears in a data grid.

__property bool Visible = {read=FVisible, write=SetVisible, default=1};

Description

To hide a field in a data grid, set Visible to false. If Visible is true, the field appears in the grid.

Note:	The Visible property has no effect if the grid has an explicit Columns value for the field. It also has no effect on controls other than TDBGrid, such as TDBEdit.


TField events

TField	Alphabetically	Legend

In TField

OnChange

OnGetText

OnSetText

OnValidate


TField events

TField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TField::OnChange

TField	See also

Occurs immediately after the data in the field is written to the record buffer.

typedef void __fastcall (__closure *TFieldNotifyEvent)(TField* Sender);

__property TFieldNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to respond to any changes in the field’s data. OnChange allows a response once the data has been successfully written to the record buffer.

When writing the value of a field to the current record buffer, the following steps occur:

1	The OnValidate event handler is called to validate the data.

2	If the OnValidate event handler accepts the current Value, the data is written to the record buffer.

3	If writing the data does not raise an exception, the OnChange event handler is called to allow a response to the change.


TField::OnGetText

TField	See also

Occurs whenever the DisplayText or Text properties of the field are referenced.

typedef void __fastcall (__closure *TFieldGetTextEvent)(TField* Sender, System::AnsiString &Text, bool DisplayText);

__property TFieldGetTextEvent OnGetText = {read=FOnGetText, write=FOnGetText};

Description

Write an OnGetText handler to perform custom processing for the DisplayText and Text properties. Use OnGetText to format the Value of the field differently when it must be edited from the format used when simply displaying the value, or use OnGetText to display something other than the field’s value when it is displayed.

The Sender parameter is the field component. The Text parameter receives the formatted text that is used by the DisplayText or Text property. The DisplayText parameter indicates whether the text will be used for display purposes only, or whether the string will be used for editing purposes.

If there is no OnGetText handler, the value of the DisplayText and Text properties is simply the value of the AsString property.


TField::OnSetText

TField	See also

Occurs when the Text property is assigned a value.

typedef void __fastcall (__closure *TFieldSetTextEvent)(TField* Sender, const System::AnsiString Text);

__property TFieldSetTextEvent OnSetText = {read=FOnSetText, write=FOnSetText};

Description

Write an OnSetText event handler to specify processing that occurs whenever Text receives a new value. If there is an OnGetText event handler that formats the Value of the field in some special way for editing purposes, OnSetText should reverse the process when parsing the edited string.

If there is no OnSetText handler, the Text property will be set by setting the AsString property.


TField::OnValidate

TField	See also

Occurs just before the data is written to the record buffer.

typedef void __fastcall (__closure *TFieldNotifyEvent)(TField* Sender);

__property TFieldNotifyEvent OnValidate = {read=FOnValidate, write=FOnValidate};

Description

Write an OnValidate event handler to validate changes made to the data in the field, just before the data is written to the current record buffer. The EditMask property allows validation of the data on a character by character basis while it is being entered by the user. OnValidate allows an application to validate the data as a whole.

When the value of a field component is assigned programmatically, validation by the EditMask is bypassed, since there is no data-aware control to enforce adherence to the mask. OnValidate allows an application to validate such data before it is posted to the database table.

To reject the current value of the field from the OnValidate event handler, throw an exception.

When writing the value of a field to the current record buffer, the following steps occur:

1	The OnValidate event handler is called to validate the data.

2	If the OnValidate event handler does not raise an exception, the data is written to the current record buffer.

3	If writing the data does not raise an exception, the OnChange event handler is called to allow a response to the change.


TField methods

TField	Alphabetically

In TField

~TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

TField

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TField methods

TField	By object

~TField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TField

Validate


TField::Assign

TField	See also 	Example

Copies the Value property of one field to another or assigns another object to the field component.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to copy the Value property from one field to another. The fields must have compatible data types.

When Source is another field object, Assign calls the AssignValue method, using the Source field’s Value property. Calling Assign with the Source parameter set to NULL assigns a blank value to the field component. Calling Assign with any other object type calls the inherited method, which allows assignment from objects that implement a TField object in their AssignTo method.


TField::AssignValue

TField	See also

Sets the field value using one of the AsInteger, AsBoolean, AsString or AsFloat properties.

void __fastcall AssignValue(const System::TVarRec &Value);

Description

Use AssignValue to assign a value to a field using the As... conversion properties. The property used depends on the type of the Value parameter:

Value	As... property used

vtInteger	AsInteger

vtBoolean	AsBoolean

vtChar	AsString

vtExtended	AsFloat

vtString	AsString

vtPChar	AsString

vtAnsiString	AsString

vtCurrency	AsCurrency

vtVariant	AsVariant

If Value is not one of the types in the table, but is of type TObject or a TObject descendant, AssignValue uses the Assign method to assign the value to the field.


TField::Clear

TField	See also

Sets the value of the field to NULL.

virtual void __fastcall Clear(void);

Description

Call the Clear method to give the field a blank value.


TField::TField

TField	See also

Creates and initializes a field component.

__fastcall virtual TField(Classes::TComponent* AOwner);

Description

Do not create TField instances. TField is an abstract base class which should not be directly instantiated. The constructor for descendant classes is usually called indirectly by using the Fields editor at design time to create a persistent field component. Dataset objects also call field constructors automatically to create dynamic field components.

After calling the parent object’s constructor, TField initializes the Visible property to true.


TField::~TField

TField	See also

Destroys an instance of TField.

__fastcall virtual ~TField(void);

Description

Do not call ~TField directly in an application. Field components are destroyed automatically by the dataset that owns them. If an application creates a descendant of TField without an owner, it should use the delete keyword to invoke the destructor indirectly.

~TField closes the dataset and deletes the instance of TField from the dataset.


TField::FocusControl

TField	See also

Forces a form’s focus to the first data-aware component associated with the field object.

void __fastcall FocusControl(void);

Description

Call FocusControl to switch the focus of the form to a data-aware control associated with the field. Because it’s possible that the field’s value can change even if its associated data-aware control doesn’t have the focus, calling FocusControl can aid in drawing attention to the new value when it fails to be validated.


TField::GetData

TField	See also 	Example

Returns the unformatted data from the field.

bool __fastcall GetData(void * Buffer);

Description

Call GetData to return the unformatted, untranslated, and uninterpreted data in a field to a buffer.

Unlike the DisplayText, Text, or AsXXX properties, GetData performs no translation or interpretation of the data. Buffer must have sufficient space allocated for the data. Use the DataSize property to determine the space required. If the data is NULL, GetData returns false and no data is transferred to Buffer. Otherwise, GetData returns true.

Note:	GetData cannot be used to read data from BLOB fields.


TField::IsBlob

TField	See also 	Example

Indicates whether the field represents the data in a binary large object (BLOB) field.

virtual bool __fastcall IsBlob() { IsBlob(__classid(TField));

Description

Call IsBlob to determine whether the field represents BLOB data. For example, before using the GetData or SetData method, call IsBlob to determine whether the method can be used. The IsBlob method for TField always returns false. Descendants of TField that implement blob fields override this method to indicate that they represent BLOB data.


TField::IsValidChar

TField	See also

Indicates whether a particular character is valid for the field.

virtual bool __fastcall IsValidChar(char InputChar);

Description

Call IsValidChar to determine if a character specified as the value of the InputChar can appear in the text representation of the value of the field. Many data-aware controls use IsValidChar to check characters entered by the user to determine if they are valid. IsValidChar returns true if InputChar can appear in the field. IsValidChar returns false if InputChar is not a valid character for the field type.

The valid characters for a field object are given by the ValidChars property. The default valid characters for each DataType are given in the following table:::

DataType	Valid characters

ftBoolean	All characters.

ftSmallInt	Digits 0 to 9, plus sign (+), and minus sign (-).

ftWord	Digits 0 to 9, plus sign (+), and minus sign (-)

ftAutoInc	Digits 0 to 9, plus sign (+), and minus sign (-)

ftDate	All characters.

ftInteger	Digits 0 to 9, plus sign (+), and minus sign (-)

ftTime	All characters

ftCurrency	Digits 0 to 9, plus sign (+), minus sign (-), the letter E (E or e) and the decimal separator from the regional settings in the Windows control panel.

ftDateTime	All characters.

ftFloat	Digits 0 to 9, plus sign (+), minus sign (-), the letter E (E or e) and the decimal separator from the regional settings in the Windows control panel

ftBCD	Digits 0 to 9, plus sign (+), minus sign (-), and the decimal separator from the regional settings in the Windows control panel.

ftString	All characters.

ftVarBytes	All characters.

ftBytes	All characters.

ftBlob	All characters.

ftDBaseOle	All characters.

ftFmtMemo	All characters.

ftGraphic	All characters.

ftMemo	All characters.

ftParadoxOle	All characters.

ftTypedBinary	All characters.

ftUnknown	All characters.

ftCursor	All characters.

Note:	For some DataTypes, such as ftGraphic, IsValidChar returns true for all characters although not every character is valid for the field. IsValidChar provides only a rough validation of input characters. More refined character-by-character validation can be provided by an edit mask. Also, the value for a field is validated as a whole when it is written to the database record.


TField::RefreshLookupList

TField	See also

Loads LookupList with all the values for LookupResultField that match distinct values of LookupKeyFields.

void __fastcall RefreshLookupList(void);

Description

Call RefreshLookupList to load the lookup cache when setting the LookupCache property at runtime or when the values of the LookupResultField or the LookupKeyFields in the LookupDataSet may have changed.


TField::SetData

TField	See also 	Example

Assigns unformatted data to the field.

void __fastcall SetData(void * Buffer);

Description

Use SetData to assign data to a field in the format that is used by the underlying database table. Ultimately, any method of setting the data for the field component calls SetData, once the data has been parsed into the physical format expected by the database table.

SetData calls the OnValidate event handler before writing the data to the current record buffer. If the data is successfully written, SetData calls the OnChange event handler.

Note:	SetData should not be used by descendants of TField that implement BLOB field types.


TField::SetFieldType

TField	See also

Provides the interface for a method that can set the DataType for the field.

enum TFieldType { ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat, ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc, ftBlob, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary, ftCursor };

virtual void __fastcall SetFieldType(TFieldType Value);

Description

SetFieldType does nothing other than provide an interface for derived classes to override to implement a method that sets the DataType for the field component. SetFieldType is useful for derived classes that can support more than one underlying data type. For example, a TBlobField may support ftBlob, ftFmtMemo, ftParadoxOle, ftDBaseOle, or ftTypedBinary.


TField::Validate

TField	See also

Generates an OnValidate event.

void __fastcall Validate(void * Buffer);

Description

Call Validate to validate the unformatted data pointed to by the Buffer parameter. Validate is called by the dataset when writing new values to the current record.

Before calling the OnValidate event handler, Validate sets up the unformatted data in Buffer so that the properties that represent the field’s value will return formatted versions of this value. The value of Buffer does not affect the value of the field outside the OnValidate event handler.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


TFieldDef

Hierarchy	Properties	Methods	See also

TFieldDef is a field definition that corresponds to a physical field of a record in a table underlying a dataset.

Unit

db

Description

A field definition is automatically created for each field in a dataset. A field definition has a corresponding TField object, but not all TField objects have a corresponding field definition object. For example, calculated fields do not have field definition objects.

There are two primary reasons for working with TFieldDef objects:

•	To obtain information about field types in a table without opening the table.

•	To create a new table from scratch.

Each field definition is held in the Items property of a TFieldDefs object, which contains all the field definitions for a dataset.

Use the properties and methods of TFieldDef determine the characteristics of the physical field it corresponds to in dataset.


TFieldDef properties

TFieldDef	Alphabetically	Legend

In TFieldDef

DataType

FieldClass

FieldNo

InternalCalcField

Precision

Required

Size

Derived from TNamedItem

DisplayName

Name

Derived from TCollectionItem

Collection

ID

Index


TFieldDef properties

TFieldDef	By object	Legend

Collection

DataType

DisplayName

FieldClass

FieldNo

ID

Index

InternalCalcField

Name

Precision

Required

Size


TFieldDef::DataType

TFieldDef	See also

Determines the type of a physical field.

enum TFieldType { ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat, ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc, ftBlob, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary, ftCursor };

__property TFieldType DataType = {read=FDataType, write=SetDataType, nodefault};

Description

Use DataType to find out what type of data the field contains. When adding field definitions to a dataset, set DataType to specify what type of field is being defined.


TFieldDef::FieldClass

TFieldDef	See also

Determines the class of the field object that corresponds to this field definition object.

__property System::TMetaClass* FieldClass = {read=GetFieldClass};

Description

Use FieldClass to find out the class of field object this field definition object corresponds to. The FieldClass is determined by the DataType of the field. For example, if the DataType is ftString, the FieldClass is __classid(TStringField).

The field object created from a field definition by the CreateField method is an instance of the FieldClass.

FieldClass is a read-only property.


TFieldDef::FieldNo

TFieldDef	See also

Identifies the physical field number used to reference the field.

__property int FieldNo = {read=GetFieldNo, write=SetFieldNo, stored=false, nodefault};

Description

Use FieldNo to find out where the physical field the field definition references is in the set of fields in the table. For example, if the value of FieldNo is 2, then the field is the second field in the table.

When adding field definitions to a dataset, set FieldNo to specify the location at which the field will be created.


TFieldDef::InternalCalcField

TFieldDef	See also

Determines if the field is a field whose value is calculated by the data source.

__property bool InternalCalcField = {read=FInternalCalcField, write=FInternalCalcField, nodefault};

Description

Read InternalCalcField to find out if the field represents a value provided by the data source that is not a field in the physical database table. Internally calculated fields are calculated by SQL servers or the Borland Database Engine in a live query view.

For example, in the following SQL statement, the dataset includes a field for the calculated value ONHAND * COST.

SELECT PARTNO, DESCRIPTION, ONHAND, COST, (ONHAND * COST) FROM PARTS

When the TQuery object has its RequestLive property set to true, the field definition for that calculated value will have InternalCalcField set to true.

InternalCalcField is a read-only property.


TFieldDef::Precision

TFieldDef	See also

Specifies the number of digits of accuracy used to store the field value.

__property int Precision = {read=FPrecision, write=SetPrecision, nodefault};

Description

When defining a BCD field, set Precision to the total number of digits stored for each field value. The value of Precision is ignored unless DataType is ftBCD.


TFieldDef::Required

TFieldDef	See also

Indicates whether a value for the physical field in the underlying table is required.

__property bool Required = {read=FRequired, write=SetRequired, nodefault};

Description

Use Required to find out if a field in a table must have a value. If Required is true, the field must have a value. If Required is false, the field can be left blank.

When adding field definitions to a dataset, set Required to specify whether new field will be required.


TFieldDef::Size

TFieldDef	See also

Reports the size associated with the field in the physical database table.

__property Word Size = {read=FSize, write=SetSize, nodefault};

Description

Use Size to determine the size associated with the corresponding physical field.

Size is meaningful only for a field definition object with one of the following TFieldType values: ftString, ftBCD, ftBytes, ftVarBytes, ftBlob, ftMemo or ftGraphic. For string and byte fields, Size is the number of bytes reserved in the table for the field. For a BCD field, Size is the number of digits following the decimal point. For a BLOB, memo, or graphic field, Size is the number of bytes from the field’s value that are stored in the actual database table.


TFieldDef methods

TFieldDef	Alphabetically

In TFieldDef

~TFieldDef

Assign

CreateField

TFieldDef

Derived from TCollectionItem

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFieldDef methods

TFieldDef	By object

~TFieldDef

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateField

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TFieldDef


TFieldDef::Assign

TFieldDef	See also

Copies the properties of one field definition to another.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to copy a field definition.  Assign checks whether the Source parameter specifies another field definition, and if so, copies the values of the Name, DataType, Size, Precision, and InternalCalcField properties.  Note that the value of FieldNo is not changed.

If the source is not a field definition, Assign calls the inherited method, which assigns properties from any object that specifies how to copy to a field definition in its AssignTo method.


TFieldDef::TFieldDef
TFieldDef::CreateField

TFieldDef	See also

Creates a TField component that matches the specifications of the TFieldDef object.

TField* __fastcall CreateField(Classes::TComponent* Owner);

Description

A dataset object calls CreateField to create the field components from the field definitions objects. Applications need never call CreateField directly.


TFieldDef::TFieldDef

TFieldDef

TFieldDef creates a new TFieldDef object.

__fastcall virtual TFieldDef(Classes::TCollection* Collection) : Db::TNamedItem(Collection) { }

Description

Do not call TFieldDef directly when creating a field definition at runtime. Instead, use the new keyword.


TFieldDef::~TFieldDef

TFieldDef

~TFieldDef frees the memory associated with the TFieldDef object.

__fastcall virtual ~TFieldDef(void) { }

Description

Do not call ~TFieldDef directly. Instead, use the delete keyword on the object, which causes ~TFieldDef to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem

TNamedItem


TFieldDefs

Hierarchy	Properties	Methods	See also

TFieldDefs holds the field definition (TFieldDef) objects that represent the physical fields underlying a dataset.

Unit

db

Description

TFieldDefs is used by a dataset to manage the field definitions it uses to create field objects that correspond to fields in the database table. TTable objects also use TFieldDefs when creating a new database table.

Use the properties and methods of TFieldDefs to:

Access a specific field definition.

Add or delete field definitions from the list.

Find out how many fields are defined.

Copy a set of field definitions to another table.


TFieldDefs properties

TFieldDefs	Alphabetically	Legend

In TFieldDefs

Items

Derived from TDefCollection

Dataset

Updated

Derived from TCollection

Count

ItemClass


TFieldDefs properties

TFieldDefs	By object	Legend

Count

Dataset

ItemClass

Items

Updated


TFieldDefs::Items
 KTFieldDefs::Items

TFieldDefs	See also

Lists the field definitions that describe each physical field in the dataset.

__property TFieldDef* Items[int Index] = {read=GetFieldDef, write=SetFieldDef};

Description

Use Items to access a particular field definition. Specify the field definition to access with the Index parameter. Index is an integer identifying the field definition’s position in the list of field definitions, in the range 0 to Count - 1.


TFieldDefs methods

TFieldDefs	Alphabetically

In TFieldDefs

~TFieldDefs

Add

AddFieldDef

Find

TFieldDefs

Update

Derived from TDefCollection

IndexOf

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFieldDefs methods

TFieldDefs	By object

~TFieldDefs

Add

AddFieldDef

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

Find

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

IndexOf

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TFieldDefs

Update


TFieldDefs.Add

TFieldDefs	See also 	Example

Creates a new field definition object and adds it to the Items property of this TFieldDefs object.

enum TFieldType { ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat, ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc, ftBlob, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary, ftCursor };

HIDESBASE void __fastcall Add(const System::AnsiString N, TFieldType T, Word S, bool R);

Description

Add is provided for backward compatibility.  The recommended way to add new field definitions to the Items property array is using the AddFieldDef method.

Add uses the values passed in the Name, DataType, Size, and Required parameters and assigns them to the respective properties of the new field definition object.

If a field definition with same name already exists, an EDatabaseError exception is thrown.


TFieldDefs::AddFieldDef

TFieldDefs	See also

Creates a new field definition object and adds it to the Items property of this TFieldDefs object.

TFieldDef* __fastcall AddFieldDef(void);

Description

Call AddFieldDef to add field definitions when creating a database table.  AddFieldDef returns the new field definition object that was added to the Items property array.  Set the properties of the returned value to specify the type of field that should be created.


TFieldDefs::TFieldDefs

TFieldDefs	See also

Creates an instance of TFieldDefs.

__fastcall TFieldDefs(TDataSet* ADataset);

Description

Applications should not need to directly instantiate TFieldDefs. TFieldDefs objects are created automatically by a dataset to specify the fields in the database.


TFieldDefs::Find

TFieldDefs	See also

Locates a field definition in the Items array from the name of the field.

HIDESBASE TFieldDef* __fastcall Find(const System::AnsiString Name);

Description

Call Find to obtain information about a particular field definition. Specify the name of the field as the value of the Name parameter.


TFieldDefs::Update

TFieldDefs	See also

Refreshes the field definitions in the Items property array to reflect the current state of the physical fields underlying the dataset.

HIDESBASE void __fastcall Update(void);

Description

Call Update to refresh the field definitions when the structure of the underlying dataset may have changed. Update updates the field definitions without opening the dataset.


TFieldDefs::~TFieldDefs

TFieldDefs

~TFieldDefs frees the memory associated with the TFieldDefs object.

__fastcall virtual ~TFieldDefs(void) { }

Description

Do not call ~TFieldDefs directly. Instead, use the delete keyword on the object, which causes ~TFieldDefs to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection

TDefCollection


TFileListBox

Hierarchy	Properties	Methods	Events	See also

TFileListBox is a specialized list box that lists all the files in a specified directory.

Unit

filectrl

Description

Add TFileListBox to a form to allow users to select a file. Use TFileListBox along with TDriveComboBox, TFilterComboBox, and TDirectoryListBox to add full file selection capabilities to a form.

To add a standard Windows 95 file open or save dialog to an application, use TOpenDialog or TSaveDialog instead.


TFileListBox properties

TFileListBox	Alphabetically	Legend

In TFileListBox

Directory

Drive

FileEdit

FileName

FileType

Mask

ShowGlyphs

Derived from TCustomListBox

Canvas

ExtendedSelect

IntegralHeight

ItemHeight

ItemIndex

Items

MultiSelect

SelCount

Selected

TopIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TFileListBox properties

TFileListBox	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

Directory

DragCursor

DragMode

Drive

Enabled

ExtendedSelect

FileEdit

FileName

FileType

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IntegralHeight

ItemHeight

ItemIndex

Items

Left

Mask

MultiSelect

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

SelCount

Selected

ShowGlyphs

ShowHint

Showing

TabOrder

TabStop

Tag

Top

TopIndex

VCLComObject

Visible

Width

WindowProc


TFileListBox::Directory

TFileListBox	See also 	Example

Specifies the directory that contains all the files listed in the file list box.

__property System::AnsiString Directory = {read=FDirectory, write=ApplyFilePath};

Description

Set Directory to update the file list box so that it displays the files in a new directory. If the form includes a TDirectoryListBox object, set the FileList property of the directory list box to have the Directory property updated automatically when the user selects a new directory.


TFileListBox::Drive

TFileListBox	See also 	Example

Specifies the drive which contains the files listed in the list box.

__property char Drive = {read=GetDrive, write=SetDrive, nodefault};

Description

Set the value of Drive to the drive that contains the files that the list box should display. When the value of Drive changes, the Directory value also changes to the current directory on the specified drive.

If the form includes a TDirectoryListBox object, set the FileList property of the directory list box to have the Drive property updated automatically when the Drive property of the directory list box changes.


TFileListBox::FileEdit

TFileListBox	See also 	Example

Links the directory list box to an edit control that displays the currently selected file.

__property Stdctrls::TEdit* FileEdit = {read=FFileEdit, write=SetFileEdit};

Description

Set FileEdit to an edit control that displays the selected file from the file list box, as is commonly done in Open and Save dialog boxes. If no file is selected in the file list box, the text of the edit control is the current value of the file list box’s Mask property.

Note:	If the user changes the text of the edit control, the results are not automatically reflected in the file list box. Use the ApplyFilePath method to update the file list box when the text of the edit control changes.


TFileListBox::FileName

TFileListBox	See also

Indicates the name of the selected file in the list box, including the path name.

__property System::AnsiString FileName = {read=GetFilePath, write=ApplyFilePath};

Description

Set FileName to initialize the file list box to a particular file. Read FileName to obtain the name of the file the user selected.

If the FileEdit property is set, the linked edit control displays the value of FileName whenever the FileName property changes.


TFileListBox::FileType

TFileListBox	See also

Determines which files are displayed in the file list box based on the attributes of the files.

enum TFileAttr { ftReadOnly, ftHidden, ftSystem, ftVolumeID, ftDirectory, ftArchive, ftNormal };

typedef Set<TFileAttr, ftReadOnly, ftNormal>  TFileType;

__property TFileType FileType = {read=FFileType, write=SetFileType, default=64};

Description

Set FileType to the type of files the list box should display. FileType can specify more than one type of file. For example, if the value of FileType is a set containing the values ftReadOnly and ftHidden, files that have either the read-only or the hidden attributes are displayed in the list box. These are the values that can occur in the FileType property:

Value	Meaning

ftReadOnly	The list box displays files with the read-only attribute.

ftHidden	The list box displays files with the hidden attribute.

ftSystem	The list box displays system files.

ftVolumeID	The list box displays the volume name.

ftDirectory	The list box displays directories.

ftArchive	The list box displays files with archive attribute.

ftNormal	The list box displays files with no special attributes.

To set the FileType property using the Object Inspector, click the FileType property to see the attribute values. Then set each value to true or false to specify whether it is included in the FileType set.

Note:	The files that are listed can also be limited by the form of their names. To restrict the files to particular names, use the Mask property or include a TFilterComboBox on the form.


TFileListBox::Mask

TFileListBox	See also 	Example

Limits which files are displayed in the file list box.

__property System::AnsiString Mask = {read=FMask, write=SetMask, stored=IsMaskStored};

Description

Set Mask to a regular expression to limit the list box to files that match the mask. The value of the mask is a file name that may include wildcards. The asterisk (*) is a wildcard which matches any number of arbitrary characters. The question mark (?) is a wildcard which matches a single arbitrary character. The file mask *.* displays all files, which is the default value.

To specify multiple file masks, separate the file mask specifications with semicolons. For example, *.CPP; *.EXE.

If the form includes a TFilterComboBox object, set the FileList property of the filter combo box to have the Mask property updated automatically when the Mask property of the filter combo box changes.


TFileListBox::ShowGlyphs

TFileListBox

Determines whether glyphs (bitmaps) appear next to the file names listed in the file list box.

__property bool ShowGlyphs = {read=FShowGlyphs, write=SetShowGlyphs, default=0};

Description

Set ShowGlyphs to true to display icons next to the files in the list that indicate the file type. Set ShowGlyphs to false to list only the file names.


TFileListBox events

TFileListBox	Alphabetically	Legend

In TFileListBox

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TFileListBox events

TFileListBox	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TFileListBox::OnChange

TFileListBox	See also

Occurs immediately after the user changes the selected file in the list.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action when the FileName property changes. If the FileEdit property has been set, the edit control is updated before the OnChange event.


TFileListBox methods

TFileListBox	Alphabetically

In TFileListBox

~TFileListBox

ApplyFilePath

TFileListBox

Update

Derived from TCustomListBox

Clear

ItemAtPos

ItemRect

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TFileListBox methods

TFileListBox	By object

~TFileListBox

ApplyFilePath

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

ItemAtPos

ItemRect

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TFileListBox

Update

UpdateControlState


TFileListBox::ApplyFilePath

TFileListBox	See also 	Example

Updates the file list box to represent a fully qualified file name.

virtual void __fastcall ApplyFilePath(const System::AnsiString EditText);

Description

Call ApplyFilePath to change the Directory, Drive, FileName, and Mask properties so that they match the values implied by the EditText parameter. For example, if an edit control is linked to the file list box using the FileEdit property, call ApplyFilePath from the OnChange event handler of the edit control to update the file list box whenever the user types a value in the edit control.

ApplyFilePath updates the Mask property only if the EditText parameter includes wildcards. If the form contains a TDirectoryListBox object that specifies this file list box object in its FileList property, the Directory and Drive properties of the directory list box object are updated as well. If the form also includes a TDriveComboBox object that specifies the directory list box in its DirList property, the Drive property of the drive combo box will also be updated. However, the Mask property of any TFilterComboBox will not be updated.


TFileListBox::TFileListBox

TFileListBox	See also

Creates an instance of TFileListBox.

__fastcall virtual TFileListBox(Classes::TComponent* AOwner);

__fastcall TDirectoryListBox(HWND ParentWindow) : Stdctrls::TCustomListBox(ParentWindow) { }

Description

Do not call TFileListBox directly when creating a file list box at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TFileListBox object. File list boxes placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TFileListBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the file list box in a non-VCL window. This syntax is used when the file list box is implemented as an ActiveX control that is embedded in a non-VCL window.

After allocating the memory for the list box, TFileListBox

•	Initializes the Mask property to *::*.

•	Initializes the FileType property to include only ftNormal.

•	Initializes the Drive and Directory properties to the current directory and fills the list box with all the files in the directory.

•	Initializes the MultiSelect property to false.

•	Initializes the Sorted property to true.

•	Initializes the Width property to 145.


TFileListBox::~TFileListBox

TFileListBox	See also

Destroys an instance of TFileListBox.

__fastcall virtual ~TFileListBox(void);

Description

Do not call ~TFileListBox directly in an application. Instead, use the delete keyword.


TFileListBox::Update

TFileListBox	See also

Refreshes the directory list for the file list box.

HIDESBASE void __fastcall Update(void);

Description

Call Update whenever the files listed by the file list box may be out of date. For example, if an application creates, renames, or deletes files, calling Update will ensure that those changes are reflected in the file list box.

The list box is updated automatically when the Drive, Directory, FileType, or Mask property is changed.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomListBox


TFiler

Hierarchy	Properties	Methods	See also

TFiler is the abstract base class for reader and writer objects, which are used for loading and saving components and their properties.

Unit

classes

Description

TFiler works with stream and component objects. It handles the internal mechanics of the streaming system that reads and writes VCL components and their associated data.  This streaming system is the mechanism by which C++Builder saves components to or reads components from disk (in .DFM files) and by which it saves and restores temporary in-memory images of components.

TFiler has two descendants, TReader and TWriter, that implement the methods introduced by TFiler. The filer type is used as a parameter to component methods that can require either a reader or writer object, depending on whether the data is read from or written to a stream. Every filer has an associated stream that is passed as a parameter to its constructor. Filer objects are usually created by the stream objects which become associated with the filer.

TFiler properties provide support for managing the streaming of owned components. Filer objects read and write the properties of components to and from a stream. Filer objects provide buffering of data to speed read and write operations.

TFiler introduces abstract methods that are customized by its descendent reader and writer objects. These include methods that enable components to load and save hidden or complex data as if it was the value of a published property.

Note:	Most of the filer properties and methods have public visibility for convenience within the VCL streaming system. The majority of them are never called directly by applications.


TFiler properties

TFiler	Alphabetically

In TFiler

Ancestor

IgnoreChildren

Root


TFiler properties

TFiler	By object

Ancestor

IgnoreChildren

Root


TFiler::Ancestor

TFiler	See also

Determines whether to write the properties of inherited components.

__property TPersistent* Ancestor = {read=FAncestor, write=FAncestor};

Description

Do not call Ancestor directly. It is used internally by the methods of writer objects to write components in inherited forms.

In Visual Form Inheritance, a writer object only needs to write the values of properties that differ from those that are inherited. It tracks each component from which properties can be inherited in Ancestor and compares properties before writing. If Ancestor is NULL, there is no corresponding component from which to inherit, and the writer object writes the component out to the stream completely.

Ancestor is only non-NULL when writing forms created with Visual Form Inheritance. The VCL streaming system uses WriteDescendent and WriteDescendentRes to write such forms to the stream.

When writing or overriding a DefineProperties method, be aware that Ancestor might be set, and it might be necessary to write or omit properties, as appropriate. Normally, DefineProperty read procedures ignore the value of Ancestor.


TFiler::IgnoreChildren

TFiler	See also

Enables a writer object to save a component without saving the components it owns.

__property bool IgnoreChildren = {read=FIgnoreChildren, write=FIgnoreChildren, nodefault};

Description

Programs rarely call IgnoreChildren directly. C++Builder uses IgnoreChildren internally to avoid writing owned components when the Root is changed during the component streaming process. A few components change Root while streaming, but this is rare.

If IgnoreChildren is true, the writer writes a component without writing any child components it owns. If IgnoreChildren is false, the writer object writes all owned objects to the stream.


TFiler::Root

TFiler	See also

Indicates which object is the root, or ultimate owner, of the objects read or written by the filer.

__property TComponent* Root = {read=FRoot, write=FRoot};

Description

Do not call Root directly. It is used internally to find the root object when streaming owned components. Root represents the ultimate owner of all the components being streamed during the current streaming process.

The ReadRootComponent and WriteRootComponent methods set Root before reading or writing their components and owned components.


TFiler methods

TFiler	Alphabetically

In TFiler

~TFiler

DefineBinaryProperty

DefineProperty

FlushBuffer

TFiler

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFiler methods

TFiler	By object

~TFiler

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DefineBinaryProperty

DefineProperty

Dispatch

FieldAddress

FlushBuffer

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TFiler


TFiler::TFiler

TFiler	See also

Creates a filer object.

__fastcall TFiler(TStream* Stream, int BufSize);

Description

Do not call TFiler directly. Instead, use the new keyword to instantiate a filer descendant at runtime, if necessary. It is seldom necessary to directly create a filer descendant because filers are automatically created by methods and routines that use them.

TFiler allocates memory for a filer object, and associates it with the stream passed in the Stream parameter, with a buffer of size BufSize.


TFiler::DefineBinaryProperty

TFiler	See also

Introduces an abstract method that allows descendants to read and write unformatted data like a property.

typedef void __fastcall (__closure *TStreamProc)(TStream* Stream);

virtual void __fastcall DefineBinaryProperty(const System::AnsiString Name, TStreamProc &ReadData, TStreamProc &WriteData, bool HasData) = 0;

Description

Each descendant filer object declares a DefineBinaryProperty method that reads or writes binary data as if the data were a property.


TFiler::DefineProperty

TFiler	See also

Introduces an abstract method that allows descendants to read or write data like a property.

typedef void __fastcall (__closure *TReaderProc)(TReader* Reader);

typedef void __fastcall (__closure *TWriterProc)(TWriter* Writer);

virtual void __fastcall DefineProperty(const System::AnsiString Name, TReaderProc &ReadData, TWriterProc &WriteData, bool HasData) = 0;

Description

Each descendant filer object declares a DefineProperty method that defines the data that the descendent object will read or write as if the data were a property.


TFiler::~TFiler

TFiler	See also

Destroys a filer object.

__fastcall virtual ~TFiler(void);

Description

Do not call ~TFiler directly in an application. Instead, use the delete keyword.

~TFiler frees memory associated with the buffer. ~TFiler is called by descendent objects in their respective destructors.


TFiler::FlushBuffer

TFiler

Introduces an abstract method that allows descendants to synchronize the filer’s buffer with its stream.

virtual void __fastcall FlushBuffer(void) = 0;

Description

Each descendant filer object defines a FlushBuffer method to provide practical implementations for synchronizing the filer object’s buffer with the associated stream.


Hierarchy

TObject


TFileStream

Hierarchy	Properties	Methods	See also

TFileStream enables applications to read from and write to a file on disk.

Unit

classes

Description

Use TFileStream to access the information in disk files. TFileStream will open a named file and provide methods to read from or write to it. If an application already has a handle to the file, opened in the appropriate mode, use THandleStream instead.


TFileStream properties

TFileStream	Alphabetically	Legend

Derived from THandleStream

Handle

Derived from TStream

Position

Size


TFileStream properties

TFileStream	By object	Legend

Handle

Position

Size


TFileStream methods

TFileStream	Alphabetically

In TFileStream

~TFileStream

TFileStream

Derived from THandleStream

Read

Seek

Write

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFileStream methods

TFileStream	By object

~TFileStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

Seek

TFileStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TFileStream::TFileStream

TFileStream	See also

Creates an instance of TFileStream.

__fastcall TFileStream(const System::AnsiString FileName, Word Mode);

Description

Do not Use TFileStream directly to instantiate a file stream for reading from or writing to the named file. Instead, use the new keyword, passing the name of the file and the way the file should be opened as parameters.

The Mode parameter indicates how the file is to be opened. The Mode parameter consists of an open mode and a share mode or’ed together. The open mode must be one of the following values:

Value	Meaning

fmCreate	TFileStream a file with the given name. If a file with the given name exists, open the file in write mode.

fmOpenRead	Open the file for reading only.

fmOpenWrite	Open the file for writing only. Writing to the file completely replaces the current contents.

fmOpenReadWrite	Open the file to modify the current contents rather than replace them.

The share mode must be one of the following values:

Value	Meaning

fmShareCompat	Sharing is compatible with the way FCBs are opened.

fmShareExclusive	Other applications can not open the file for any reason.

fmShareDenyWrite	Other applications can open the file for reading but not for writing.

fmShareDenyRead	Other applications can open the file for writing but not for reading.

fmShareDenyNone	No attempt is made to prevent other applications from reading from or writing to the file.

If the file can not be opened, TFileStream will throw an exception.


TFileStream::~TFileStream

TFileStream	See also

Destroys an instance of TFileStream.

__fastcall virtual ~TFileStream(void);

Description

Do not call ~TFileStream directly in an application. Instead, use the delete keyword, which takes an indirect reference to the file stream.

~TFileStream releases the Handle for the file stream before freeing the object.


Accessibility

Read-only


Hierarchy

TObject

TStream

THandleStream


 TFindDialog

Hierarchy	Properties	Methods	Events	See also

TFindDialog displays a Find dialog that allows users to search for text in a file.

Unit

dialogs

Description

The TFindDialog component displays a modeless Windows dialog box that promps the user for a search string. The dialog does not appear at runtime until it is activated by a call to the Execute method.


TFindDialog properties

TFindDialog	Alphabetically	Legend

In TFindDialog

FindText

Left

Options

Position

Top

Derived from TCommonDialog

Ctl3D

Handle

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TFindDialog properties

TFindDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DesignInfo

FindText

Handle

HelpContext

Left

Name

Options

Owner

Position

Tag

Top

VCLComObject


TFindDialog::FindText

TFindDialog 	Example

Contains the search string.

__property System::AnsiString FindText = {read=GetFindText, write=SetFindText};

Description

FindText contains the text string that the user wants to search for. When the user clicks the Find Next button, the text in the dialog’s edit box is automatically assigned to FindText. To make a default text string appear in the edit box when the dialog opens, assign a value to FindText in the Object Inspector or in program code.


TFindDialog::Left

TFindDialog	See also

Determines the X coordinate (horizontal position) of the Find dialog’s upper left corner.

__property int Left = {read=GetLeft, write=SetLeft, nodefault};

Description

Left holds the same value as the first integer in Position. This property is maintained for compatibility with older applications.


TFindDialog::Options

TFindDialog	See also 	Example

Determines the appearance and behavior of the Find dialog.

enum TFindOption { frDown, frFindNext, frHideMatchCase, frHideWholeWord, frHideUpDown, frMatchCase, frDisableMatchCase, frDisableUpDown, frDisableWholeWord, frReplace, frReplaceAll, frWholeWord, frShowHelp };

typedef Set<TFindOption, frDown, frShowHelp>  TFindOptions;

__property TFindOptions Options = {read=FOptions, write=FOptions, default=1};

Description

The possible values of Options are

Value	Meaning

frDisableMatchCase	Disables (grays) the Match Case check box.

frDisableUpDown	Disables (grays) the Up and Down buttons, used to determine the direction of the search.

frDisableWholeWord	Disables (grays) the Match Whole Word check box.

frDown	Selects the Down button by default when the dialog opens. If the frDown flags is off, Up is selected when the dialog opens. (By default, frDown is on::)

frFindNext	This flag is turned on when the user clicks the Find Next button and turned off when the dialog closes.

frHideMatchCase	Removes the Match Case check box from the dialog.

frHideWholeWord	Removes the Match Whole Word check box from the dialog.

frHideUpDown	Removes the Up and Down buttons from the dialog.

frMatchCase	This flag is turned on (off) when the user selects (deselects) the Match Case check box. To select the check box by default when the dialog opens, set frMatchCase at design time.

frReplace	Applies to TReplaceDialog only. This flag is set by the system to indicate that the application should replace the current occurrence (and only the current occurrence) of the FindText string with the ReplaceText string.

frReplaceAll	Applies to TReplaceDialog only. This flag is set by the system to indicate that the application should replace all occurrences of the FindText string with the ReplaceText string.

frShowHelp	Displays a Help button in the dialog.

frWholeWord	This flag is turned on (off) when the user selects (deselects) the Match Whole Word check box. To select the check box by default when the dialog opens, set frWholeWord at design time.

By default, all options except frDown are off.


TFindDialog::Position

TFindDialog	See also 	Example

Determines the position of the Find dialog on the screen.

__property tagPOINT Position = {read=GetPosition, write=SetPosition};

Description

Position gives the pixel coordinates of the dialog’s upper left corner.


TFindDialog.Top

TFindDialog	See also

Determines the Y coordinate (vertical position) of the Find dialog’s upper left corner.

__property int Top = {read=GetTop, write=SetTop, nodefault};

Description

Top holds the same value as the second integer in Position. This property is maintained for compatibility with older applications.


TFindDialog events

TFindDialog	Alphabetically	Legend

In TFindDialog

OnFind

Derived from TCommonDialog

OnClose

OnShow


TFindDialog events

TFindDialog	By object	Legend

OnClose

OnFind

OnShow


TFindDialog::OnFind

TFindDialog	See also	Example

Occurs when the user clicks the Find Next button.

__property Classes::TNotifyEvent OnFind = {read=FOnFind, write=FOnFind};

Description

Write an OnFind event handler to perform the requested search when the user clicks Find Next in the dialog.  Use the Options flags to determine how the search is conducted.


TFindDialog methods

TFindDialog	Alphabetically

In TFindDialog

~TFindDialog

CloseDialog

Execute

TFindDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TFindDialog methods

TFindDialog	By object

~TFindDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CloseDialog

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TFindDialog


TFindDialog::CloseDialog

TFindDialog

Closes the Find dialog box.

void __fastcall CloseDialog(void);

Description

CloseDialog closes the dialog box and frees its window handle, but leaves most properties of the TFindDialog (including FindText) unchanged.


TFindDialog::TFindDialog

TFindDialog	See also

Creates and initializes a TFindDialog instance.

__fastcall virtual TFindDialog(Classes::TComponent* AOwner);

Description

Do not call TFindDialog directly. Instead, use the keyword new, which returns an indirect reference to the new Find dialog. TFindDialog objects placed on a form at design time are created automatically.

The TFindDialog method generates a TFindDialog instance, but the new dialog does not appear on the form at runtime until the Execute method is called.


TFindDialog::~TFindDialog

TFindDialog	See also

Destroys the TFindDialog and frees its memory.

__fastcall virtual ~TFindDialog(void);

Description

Do not call ~TFindDialog directly. Instead, use the delete keyword on the object, which causes ~TFindDialog to be invoked automatically.


TFindDialog::Execute

TFindDialog 	Example

Displays the Find dialog.

virtual bool __fastcall Execute(void);

Description

Execute opens the Find dialog, returning true when a window handle is successfully allocated. If the dialog is already open when Execute is called, Execute brings the dialog to the top, activates its parent form, and returns true.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog


TFieldDataLink

Hierarchy	Properties	Methods	Events	See also

TFieldDataLink helps a data-aware windowed control manage its link to a TField object and respond to data events.

Unit

dbctrls

Description

Use TFieldDataLink as a member in any data-aware object that needs to link to a TField object and respond to data events or track database information. The data-aware object must be a descendant of TWinControl.

The constructor of the data-aware object should call the constructor of the TFieldDataLink member, and initialize any relevant event-handlers. The data-aware object can then link to a TField object by using the FieldName property of the TFieldDataLink and can link to a dataset by using the DataSource property of the TFieldDataLink.


TFieldDataLink properties

TFieldDataLink	Alphabetically	Legend

In TFieldDataLink

CanModify

Control

Editing

Field

FieldName

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

ReadOnly

RecordCount


TFieldDataLink properties

TFieldDataLink	By object	Legend

Active

ActiveRecord

BufferCount

CanModify

Control

DataSet

DataSource

DataSourceFixed

Editing

Field

FieldName

ReadOnly

RecordCount


TFieldDataLink::CanModify

TFieldDataLink	See also

Indicates whether the Control can modify a field in the database table managed by TFieldDataLink.

__property bool CanModify = {read=GetCanModify, nodefault};

Description

Read CanModify to find out whether the Control that owns this TFieldDataLink is able to alter the data in the database that this field represents. CanModify may be false because the control is read-only, or because the underlying field does not permit updates.


TFieldDataLink::Control

TFieldDataLink	See also

Specifies the data-aware component that uses this TFieldDataLink object to manage its link to a TField object.

__property Classes::TComponent* Control = {read=FControl, write=FControl};

Description

This property should only be set by components that use TFieldDataLink to manage the link to a TField object. In their own constructors, these data-aware components can set the Control property of their TFieldDataLink member to this, after calling the TFieldDataLink constructor.

The Control property can be read to access methods of the component when processing data events.


TFieldDataLink::Editing

TFieldDataLink	See also

Indicates whether the dataset that contains the associated field is in edit mode.

__property bool Editing = {read=FEditing, nodefault};

Description

Use Editing to determine whether the value of the field associated with this TDataLink can currently be edited. If Editing is false, calling the Edit method may drive the dataset into edit mode. The Edit method may not be successful, however, if the field cannot be edited. For example, if the CanModify property is false, Editing will always be false.


TFieldDataLink::Field

TFieldDataLink	See also

Specifies the field component managed by this TFieldDataLink object.

__property Db::TField* Field = {read=FField};

Description

Read Field to gain access to the field object to which the Control of this TFieldDataLink is bound.

Note:	Before using Field to alter the value of a field’s contents, applications should check the CanModify property. The Field object will not be aware of all constraints to edits for this TFieldDataLink.


TFieldDataLink::FieldName

TFieldDataLink	See also

Specifies the name of the field to which the Control of this TFieldDataLink is bound.

__property System::AnsiString FieldName = {read=FFieldName, write=SetFieldName};

Description

Use FieldName to implement the FieldName property of the data-aware control that owns the TFieldDataLink. Setting FieldName links the TFieldDataLink, and hence the control, to the field in the dataset with that name.


TFieldDataLink events

TFieldDataLink	Alphabetically

In TFieldDataLink

OnActiveChange

OnDataChange

OnEditingChange

OnUpdateData


TFieldDataLink events

TFieldDataLink	By object

OnActiveChange

OnDataChange

OnEditingChange

OnUpdateData


TFieldDataLink::OnActiveChange

TFieldDataLink	See also

Occurs when the Active property of the TFieldDataLink changes.

__property Classes::TNotifyEvent OnActiveChange = {read=FOnActiveChange, write=FOnActiveChange};

Description

Write an OnActiveChange event handler to take specific action immediately after the dataset transitions into or out of an active state. OnActiveChange is particularly useful for updating objects to reflect changes that occurred while the dataset was not active, as the object can not respond to events while its TFieldDataLink is not Active.


TFieldDataLink::OnDataChange

TFieldDataLink	See also

Occurs when the contents of the dataset change.

__property Classes::TNotifyEvent OnDataChange = {read=FOnDataChange, write=FOnDataChange};

Description

Write an OnDataChange event handler to take specific action when there is a change to the contents of the field. OnDataChange allows the control object to respond when the dataset sends out notifications that the data has changed.


TFieldDataLink::OnEditingChange

TFieldDataLink	See also

Occurs after the DataSource transitions into or out of an editing state.

__property Classes::TNotifyEvent OnEditingChange = {read=FOnEditingChange, write=FOnEditingChange};

Description

Write an OnEditingChange event handler to take specific action when the DataSource transitions into or out of an editing state. This event can be used to create visual indications of the editing state in the control that uses this TFieldDataLink.


TFieldDataLink::OnUpdateData

TFieldDataLink	See also

Occurs when it is time to post any pending changes to the dataset.

__property Classes::TNotifyEvent OnUpdateData = {read=FOnUpdateData, write=FOnUpdateData};

Description

Write an OnUpdateData event handler to write the data in the representation of the field to the database record. Posting the data from within OnUpdateData does not trigger a call to OnDataChange.


TFieldDataLink methods

TFieldDataLink	Alphabetically	Legend

In TFieldDataLink

~TFieldDataLink

ActiveChanged

Edit

EditingChanged

FocusControl

LayoutChanged

Modified

RecordChanged

Reset

TFieldDataLink

UpdateData

Derived from TDataLink

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFieldDataLink methods

TFieldDataLink	By object	Legend

~TFieldDataLink

ActiveChanged

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Edit

EditingChanged

FieldAddress

FocusControl

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LayoutChanged

MethodAddress

MethodName

Modified

NewInstance

RecordChanged

Reset

SafeCallException

TFieldDataLink

UpdateData

UpdateRecord


TFieldDataLink::ActiveChanged

TFieldDataLink	See also

Generates an OnActiveChanged event.

virtual void __fastcall ActiveChanged(void);

Description

Changes to the Active property trigger the ActiveChanged method. If an OnActiveChange event handler is assigned, ActiveChanged calls this event handler. If ActiveChanged is triggered by a transition into an active state, then before calling the event handler, ActiveChanged makes sure that the Field for this TFieldDataLink is still valid.


TFieldDataLink::Edit

TFieldDataLink	See also

Attempts to drive the DataSource into an editing state if it is not already in one.

HIDESBASE bool __fastcall Edit(void);

Description

Use Edit to try to ensure that the contents of the field can be modified. A return value of true indicates that the field was already in an editing state, or that the DataSource was successfully changed to allow editing. A return value of false indicates that the DataSource could not be changed to allow editing. For example, if the CanModify property is false, Edit fails, and returns false.


TFieldDataLink::EditingChanged

TFieldDataLink	See also

Enforces the CanModify property when the field binding changes.

virtual void __fastcall EditingChanged(void);

Description

Changing the field binding can change the validity of the CanModify property, since individual field components can disallow edits. If TFieldDataLink is in an editing state when the Field property is changed, EditingChanged checks the CanModify property. If CanModify is false, it changes back out of the editing state.

Note:	This differs significantly from the EditingChanged method of the parent object TDataLink. The functionality of the inherited method is replaced in TFieldDataLink by the OnEditingChange event handler.


TFieldDataLink::FocusControl

TFieldDataLink	See also

Sets the input focus to Control.

virtual void __fastcall FocusControl(Db::TFieldRef Field);

Description

Call FocusControl to give the Control associated with this TFieldDataLink object the input focus. FocusControl checks whether the Control can receive input focus, and if so, calls its SetFocus method to move focus to the Control.


TFieldDataLink::LayoutChanged

TFieldDataLink	See also

Ensures that the Field property is valid after changes in the layout of a container of the Control for this TFieldDataLink.

virtual void __fastcall LayoutChanged(void);

Description

LayoutChanged is called after changes in the layout of one of the containers of the Control for this TFieldDataLink that might change the validity of its field binding. For example, if the Control is embedded within a TCustomDBGrid, and one of the columns is deleted, the Field property for the Control might become invalid.


TFieldDataLink::Modified

TFieldDataLink	See also

Keeps track of changes made to the data for this field that are not yet written to the record in the dataset.

void __fastcall Modified(void);

Description

Call Modified when the Control for this TFieldDataLink begins processing edits.


TFieldDataLink::RecordChanged

TFieldDataLink	See also

Generates an OnDataChange event.

virtual void __fastcall RecordChanged(Db::TField* Field);

Description

Applications can not call this protected method. It is triggered automatically when the contents of the current record change. RecordChanged calls the OnDataChange event handler if there is one.


TFieldDataLink::Reset

TFieldDataLink	See also

Ignores all pending changes and Generates an OnDataChange event.

void __fastcall Reset(void);

Description

The Control that owns a TFieldDataLink object calls its Reset method to process a UI action that cancels edits to the field. Reset calls the OnDataChange event handler without writing any pending changes to the record in the dataset.


TFieldDataLink::UpdateData

TFieldDataLink	See also

Generates an OnUpdateData event.

virtual void __fastcall UpdateData(void);

Description

UpdateData overrides the default UpdateData method to call the OnUpdateData event handler where the data-aware control can write any pending edits to the record in the dataset.


Accessibility

Read-only


TFieldDataLink::TFieldDataLink

TFieldDataLink

Creates a new TFieldDataLink object.

__fastcall TFieldDataLink(void) : Db::TDataLink() { }

Description

Applications should never need to create a TFieldDataLink component. Component writers will need to instantiate a TFieldDataLink object from the constructor of data-aware controls. To do so, use the new keyword, which returns an indirect reference to the new TFieldDataLink object.


TFieldDataLink::~TFieldDataLink

TFieldDataLink

Frees the memory associated with the TFieldDataLink object.

__fastcall virtual ~TFieldDataLink(void) { }

Description

Do not call ~TFieldDataLink directly. Instead, use the delete keyword on the object, which causes ~TFieldDataLink to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


TFloatField

Hierarchy	Properties	Methods	Events	See also

TFloatField represents a field that contains floating-point values in a dataset.

Unit

db

Description

Floating-point fields can hold values in the range from (positive or negative) 5.0 * 10-324 to 1.7 * 10308 with an accuracy of 15 digits.

TFloatField introduces new properties to

•	Convert between floating-point values and other data types.

•	To limit the range or precision of valid values that the field will permit.

•	To format the value for display purposes.

As a descendent of TNumericField, TFloatField includes many properties, methods, and events that are useful for managing the value and properties of a numeric field in a database.

TFloatField is the direct ancestor of the TCurrencyField component.


TFloatField properties

TFloatField	Alphabetically	Legend

In TFloatField

AsFloat

AsInteger

AsString

AsVariant

Currency

DataSize

MaxValue

MinValue

Precision

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TFloatField properties

TFloatField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

Currency

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

Precision

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TFloatField::AsFloat

TFloatField	See also

Represents the value of the floating-point field.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

Floating-point values need no conversion, because the native storage format of a floating-point field is a Double. AsFloat provides a uniform interface that allows applications to get or set floating-point values with generic field components when the internal storage format of the data is not known.

If the value assigned to the field does not fall within the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TFloatField::AsInteger

TFloatField	See also 	Example

Represents the value of the floating-point field as an integer value.

__property int AsInteger = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

Use AsInteger to

•	Assign an integer value to the floating-point field.

•	Assign the floating-point field value to an integer.

AsInteger converts floating point values to integers by truncating the decimal portion. If a value assigned to the field is not within the range established by the MinValue and the MaxValue properties, an EDatabaseError exception is thrown.


TFloatField::AsString

TFloatField	See also

Represents the value of a floating-point field as a string value.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to

•	Assign the floating-point field value to string value.

•	Assign a string value to the floating-point field.

For example, this code assigns a string value to floating-point field value:

MyFloatField->AsString = "13.5";

To assign floating-point field value to a string, use code similar to this:

AnsiString NewString = MyFloatField->AsString;

If the string assigned to the field does not represent a valid floating-point value in the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TFloatField::AsVariant

TFloatField	See also

Represents the value of a floating-point field as a variant value.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the floating-point field value to a variant variable.

•	Assign a variant value to the floating-point field.

Using variants is useful when the actual field type and the format of the data are unknown.

If the value assigned to the field does not fall within the range specified with MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TFloatField::currency

TFloatField	See also

Determines whether the value in the field should be formatted as a currency value.

__property bool currency = {read=FCurrency, write=SetCurrency, default=0};

Description

Use the currency property to specify the formatting of the field for viewing and editing in a data-aware control.

The field is formatted for display using the DisplayFormat property if it is assigned. If DisplayFormat is not assigned, currency determines how the field is formatted for display. If currency is true, the value is formatted for display using the FloatToText function with the ffCurrency formatting code. If currency is false, the value is formatted with the ffGeneral format.

The field is formatted for editing purposes using the EditFormat (or DisplayFormat) property if it is assigned. If neither EditFormat nor DisplayFormat is assigned, currency determines how the field is formatted for editing. If currency is true, the value is formatted for editing using the FloatToText function with the ffFixed formatting code. If currency is false, the value is formatted with the ffGeneral format.


TFloatField::DataSize

TFloatField	See also 	Example

Specifies the amount of memory needed to store the value of a float field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a float field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For float fields, DataSize is always 8. Database tables store float fields as a double, which is the same as the type used by TFloatField.


TFloatField::MaxValue

TFloatField	See also

Limits the maximum value in the floating-point field.

__property double MaxValue = {read=FMaxValue, write=SetMaxValue};

Description

Use MaxValue to get or set the maximum value that can be entered into the field. If a value greater than MaxValue is entered, an EDatabaseError exception is thrown.


TFloatField::MinValue

TFloatField	See also

Limits the minimum value in the floating-point field.

__property double MinValue = {read=FMinValue, write=SetMinValue};

Description

Use MinValue to get or set the minimum value that can be entered into the field. If a value smaller than MinValue is entered, an EDatabaseError exception is thrown.


TFloatField::Precision

TFloatField

Determines the precision used in formatting the value in a floating-point field.

__property int Precision = {read=FPrecision, write=SetPrecision, default=15};

Description

Use Precision set the number of digits beyond the decimal point the value should be formatted to before rounding begins. Precision affects the format of the floating-point value when it is displayed as a text string, not the actual floating-point value that is stored in the field.

The default value of Precision is 15 decimal places.

Note:	Precision must be greater than or equal to 2. Trying to set Precision to a value less than 2 changes the value of Precision to 2.


TFloatField::Value
Value

TFloatField	See also

Specifies the value of the floating-point field.

__property double Value = {read=GetAsFloat, write=SetAsFloat};

Description

Use Value to read data from and write data to a floating-point component at runtime. Using the Value property is the same as using the AsFloat property. Use Value when you know the field component is a floating-point field. Use AsFloat when working with a generic field component.


TFloatField events

TFloatField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TFloatField events

TFloatField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TFloatField methods

TFloatField	Alphabetically

In TFloatField

~TFloatField

TFloatField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TFloatField methods

TFloatField	By object

~TFloatField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TFloatField

Validate


TFloatField::TFloatField

TFloatField 	See also

Creates a new TFloatField object.

__fastcall virtual TFloatField(Classes::TComponent* AOwner);

Description

Do not call TFloatField directly to create and initialize an instance of TFloatField. Instead, use the new keyword, passing the Owner parameter to give the floating-point field an owner. It is seldom necessary to create floating-point fields in an application because a floating-point field component is instantiated automatically for all floating-point fields in a dataset.

After calling the parent class’s constructor, TFloatField sets the DataType to ftFloat, and the Precision to 15.


TFloatField::~TFloatField

TFloatField

Frees the memory associated with the TFloatField object.

__fastcall virtual ~TFloatField(void) { }

Description

Do not call ~TFloatField directly. Instead, use the delete keyword on the object, which causes ~TFloatField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField


TFilterComboBox

Hierarchy	Properties	Methods	Events	See also

TFilterComboBox is a specialized combo box that presents the user with a choice of file filters.

Unit

filectrl

Description

Add a filter combo box to a form that includes a file selection control to provide a set of predefined file filters. Use TFilterComboBox along with TDriveComboBox, TDirectoryListBox, and TFileListBox to add full file selection capabilities to a form.

To add a standard Windows 95 file open or save dialog to an application, use TOpenDialog or TSaveDialog instead.


TFilterComboBox properties

TFilterComboBox	Alphabetically	Legend

In TFilterComboBox

FileList

Filter

Mask

Derived from TCustomComboBox

Canvas

DroppedDown

ItemIndex

Items

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TFilterComboBox properties

TFilterComboBox	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

DroppedDown

Enabled

FileList

Filter

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

ItemIndex

Items

Left

Mask

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TFilterComboBox::FileList

TFilterComboBox	See also 	Example

Links the filter combo box to a file list box control.

__property TFileListBox* FileList = {read=FFileList, write=SetFileListBox};

Description

If the form includes a TFileListBox object to display a list of files to choose from, set FileList to allow the filter combo box to limit which files are displayed in the list box. Once the two controls are connected, whenever a new filter is selected using a filter combo box, the file list box displays the files that match the selected filter.


TFilterComboBox::Filter

TFilterComboBox	See also 	Example

Contains all the file masks displayed in the filter combo box.

__property System::AnsiString Filter = {read=FFilter, write=SetFilter, stored=IsFilterStored};

Description

Set the Filter property to specify the names that appear in the filter combo box, along with the masks associated with each name. Each mask is a file name that may include wildcards. The asterisk (*) is a wildcard which matches any number of arbitrary characters. The question mark (?) is a wildcard which matches a single arbitrary character. When the application runs, the file filter the user selects in the filter combo box becomes the value of the Mask property.

To create the value of Filter for a single file type, follow these steps:

1	Type some meaningful text to indicate the type of file.

2	Type a | character (vertical bar).

3	Type the file filter.

Don't put in any spaces around the | character in the string.

Here's an example:

FilterComboBox1->Filter = "Text files|*.TXT";

If Filter is set to this string, the string “Text files” appears in the filter combo box. When the user selects “Text files”, the mask is set to “*.TXT”.

To specify multiple file filters, extend the value of Filter, separating each file name/mask combination with a | character. Filter can specify an any number of file filters, as long as the string is less than 255 characters.

Here's an example of two file filters that could be specified as the value of the Filter property:

"Text files (*.TXT)|*.TXT|C++ files (*.CPP)|*.CPP"

The previous example includes the file filters in parentheses in the text parts. This isn't required, but it's a common convention that helps users understand what to expect when they select a file filter.

The mask portion can include multiple file specifiers if they are separated with semicolons:

"All files|*.TXT;*.CPP;*.RC"


TFilterComboBox::Mask

TFilterComboBox	See also 	Example

Specifies the mask associated with the string selected in the filter combo box.

__property System::AnsiString Mask = {read=GetMask};

Description

Read Mask to obtain the mask that was selected by the user.

When the user uses the filter combo box to select a new filter, the mask associated with the selected file type becomes the value of the Mask property. If a file list box is linked to the filter combo box with the FileList property, the file list will update when the value of Mask changes.


TFilterComboBox events

TFilterComboBox	Alphabetically	Legend

Derived from TCustomComboBox

OnChange

OnDropDown

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TFilterComboBox events

TFilterComboBox	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDropDown

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnStartDrag


TFilterComboBox methods

TFilterComboBox	Alphabetically

In TFilterComboBox

~TFilterComboBox

TFilterComboBox

Derived from TCustomComboBox

Clear

SelectAll

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TFilterComboBox methods

TFilterComboBox	By object

~TFilterComboBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TFilterComboBox

Update

UpdateControlState


TFilterComboBox::TFilterComboBox

TFilterComboBox	See also

Creates and initializes an instance of TFilterComboBox.

__fastcall virtual TFilterComboBox(Classes::TComponent* AOwner);

__fastcall TFilterComboBox(HWND ParentWindow) : Stdctrls::TCustomComboBox(ParentWindow) { }

Description

Do not call TFilterComboBox directly when creating a filter combo box at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TFilterComboBox object. Filter combo boxes placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TFilterComboBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the filter combo box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After allocating the memory for the combo box, TFilterComboBox initializes the Mask property to *.* and initializes the Style property to csDropDownList.


TFilterComboBox::~TFilterComboBox

TFilterComboBox	See also

Destroys an instance of TFilterComboBox.

__fastcall virtual ~TFilterComboBox(void);

Description

Do not call ~TFilterComboBox directly in an application. Instead, use the delete keyword.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomComboBox


TFont

Hierarchy	Properties	Methods	Events	See also

TFont encapsulates a windows logical font.

Unit

graphics

Description

TFont to describes font characteristics used when displaying text. TFont defines a set of characters by specifying the height, font family (typeface), attributes (such as bold or italic) and so on.


TFont properties

TFont	Alphabetically	Legend

In TFont

Charset

Color

FontAdapter

Handle

Height

Name

Pitch

PixelsPerInch

Size

Style

Derived from TGraphicsObject

OwnerCriticalSection


TFont properties

TFont	By object	Legend

Charset

Color

FontAdapter

Handle

Height

Name

OwnerCriticalSection

Pitch

PixelsPerInch

Size

Style


TFont::Charset

TFont	See also

Specifies the character set of the font.

typedef Byte TFontCharset;

__property TFontCharset Charset = {read=GetCharset, write=SetCharset, nodefault};

Description

Set Charset to identify the character set of the font. Each typeface (specified by the Name property) supports one or more character sets. Check the information supplied by the font vendor to determine what values of Charset are valid.

The following table lists the predefined constants provided for standard character sets:

Constant	Value	Description

ANSI_CHARSET	0	ANSI characters.

DEFAULT_CHARSET	1	Font is chosen based solely on Name and Size. If the described font is not available on the system, Windows will substitute another font.

SYMBOL_CHARSET	2	Standard symbol set.

MAC_CHARSET	77	Macintosh characters. Not available on NT 3.51.

SHIFTJIS_CHARSET	128	Japanese shift-jis characters.

HANGEUL_CHARSET	129	Korean characters (Wansung).

JOHAB_CHARSET	130	Korean characters (Johab). Not available on NT 3.51

GB2312_CHARSET	134	Simplified Chinese characters (mainland china).

CHINESEBIG5_CHARSET	136	Traditional Chinese characters (taiwanese).

GREEK_CHARSET	161	Greek characters. Not available on NT 3.51.

TURKISH_CHARSET	162	Turkish characters. Not available on NT 3.51

VIETNAMESE_CHARSET	163	Vietnamese characters. Not available on NT 3.51.

HEBREW_CHARSET	177	Hebrew characters. Not available on NT 3::51

ARABIC_CHARSET	178	Arabic characters. Not available on NT 3::51

BALTIC_CHARSET	186	Baltic characters. Not available on NT 3::51.

RUSSIAN_CHARSET	204	Cyrillic characters. Not available on NT 3::51.

THAI_CHARSET	222	Thai characters. Not available on NT 3::51

EASTEUROPE_CHARSET	238	Includes diacritical marks for eastern european countries. Not available on NT 3::51.

OEM_CHARSET	255	Depends on the codepage of the operating system.


TFont::Color

TFont	See also 	Example

Specifies the color of the text.

__property TColor Color = {read=FColor, write=SetColor, nodefault};

Description

Use Color to specify the color of the text characters (as opposed to the background color). If Color is set to a dithered color, the text appears in the closest non-dithered value.


TFont::FontAdapter

TFont	See also

Designates an interface for providing the font information to ActiveX controls.

__property _di_IChangeNotifier FontAdapter = {read=FNotify, write=FNotify};

Description

Do not use the FontAdapter property. FontAdapter is used internally by ActiveX controls to communicate font information through an OLE interface.


TFont::Handle

TFont	See also

Indicates the Windows GDI font object handle.

__property HFONT Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

Use Handle as a parameter when calling Windows API functions that require a font handle. Set Handle to make the TFont object represent the Windows font indicated by the font handle. Setting Handle releases the current Windows font resource.

Note:	When possible, change a font by setting the other properties of TFont rather than using the Handle property. Setting Handle does not reset the properties that describe the font. However, an OnChange event does occur when Handle is set directly by an application.


TFont::Height

TFont	See also

Specifies the height of the font.

__property int Height = {read=GetHeight, write=SetHeight, nodefault};

Description

Use Height to specify the height of the font in pixels. If the value is negative, the internal leading that appears at the top of each line of text is not measured. If the value is positive, Height represents the height of the characters plus the internal leading.

To specify the size of the font in points, use the Size property instead. Users usually specify font size in points, while applications may be concerned with the actual size of the font in pixels when displaying the font on the screen.

The value of Height can be optained from the point size using this formula:

Font.Height = -Font.Size * Font.PixelsPerInch/ 72

When the Height property has a positive value, the Size property has a negative value. When the Size property has a positive value, the Height property has a negative value.


TFont::Name

TFont	See also	Example

Identifies the typeface of the font.

__property System::AnsiString Name = {read=GetName, write=SetName};

Description

Use Name to specify the typeface of the font. If the font family described by Name includes multiple character sets, be sure to set the CharSet property as well.

Note:	If the combination of Name, CharSet, Pitch, and Size specifies a font that is not available on the system, Windows substitutes a different font.


TFont::Pitch

TFont	See also

Specifies whether the characters in the font all have the same width.

enum TFontPitch { fpDefault, fpVariable, fpFixed };

__property TFontPitch Pitch = {read=GetPitch, write=SetPitch, default=0};

Description

Each typeface has an associated pitch. The characters in fixed-pitch fonts are all the same width. The characters in variable-pitch fonts differ in width. Fixed pitch fonts are generally used for representing source code, because they allow the indentation to line up properly. Variable pitch fonts are generally used to give text a more natural appearance.

Here are the possible values for Pitch:

Value	Meaning

fpDefault	The font pitch is set to the default value, which depends on the font specified in the Name property.

fpFixed	The font pitch is set to fixed. All characters in the font have the same width.

fpVariable	The font pitch is set to variable. The characters in the font have different widths.

Setting the Pitch of a fixed-pitch font to fpVariable or a variable-pitch font to fpFixed will cause Windows to find what it considers the best match to all of the font characteristics that have been specified. This might have no effect on the appearance of a font, or might cause Windows to substitute a different font with the appropriate pitch. For example, setting the pitch of MS Serif (a variable-pitch font) to fpFixed causes Courier to be displayed.


TFont::PixelsPerInch

TFont	See also

Indicates the conversion factor between logical inches and the pixels of the device (printer or screen) using the font.

__property int PixelsPerInch = {read=FPixelsPerInch, write=FPixelsPerInch, nodefault};

Description

PixelsPerInch is used to ensure that when a font is copied from the form's canvas to the printer, the font is the same size in points. The PixelsPerInch property affects printer fonts only and should not be modified.

To modify the size of a font, use the Size or Height properties.


TFont::Size

TFont	See also

Specifies the height of the font in points.

__property int Size = {read=GetSize, write=SetSize, stored=false, nodefault};

Description

Use Size to specify the point size of the font. If the value is negative, the internal leading that appears at the top of each line of text is included. If the value is positive, Size represents the height of the characters but not the internal leading.

To determine the size of the font in pixels, use the Height property instead. The value of Size can be optained from the height in pixels using this formula:

Font.Size = -Font.Height * 72 / Font.PixelsPerInch

When the Size property has a positive value, the Height property has a negative value. When the Height property has a positive value, the Size property has a negative value.


TFont::Style

TFont	See also

Determines whether the font is normal, italic, underlined, bold, and so on.

enum TFontStyle { fsBold, fsItalic, fsUnderline, fsStrikeOut };

typedef Set<TFontStyle, fsBold, fsStrikeOut>  TFontStyles;

__property TFontStyles Style = {read=GetStyle, write=SetStyle, nodefault};

Description

Use Style to add special characteristics to characters that use the font. Style is a set containing zero or more values from the following:

Value	Meaning

fsBold	The font is boldfaced.

fsItalic	The font is italicized.

fsUnderline	The font is underlined.

fsStrikeout	The font is displayed with a horizontal line through it.


TFont events

TFont	Alphabetically

Derived from TGraphicsObject

OnChange


TFont events

TFont	By object

OnChange


TFont methods

TFont	Alphabetically

In TFont

~TFont

Assign

TFont

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFont methods

TFont	By object

~TFont

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TFont


TFont::Assign

TFont	See also 	Example

Copies the properties of another TFont object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to set the properties of the font to match the characteristics of the Source object. If Source is another TFont object, Assign matches the font characteristics of the source. Assign does not copy the PixelsPerInch property, so this method can be used to copy a screen font to a printer font, or vice versa.

If the Source parameter is not another TFont object, Assign calls the inherited method so that the font can be copied from any object that can assign font properties in its AssignTo method.


TFont::TFont

TFont	See also

Creates and initializes an instance of TFont.

__fastcall TFont(void);

Description

Do not call TFont directly. Instead, use the keyword new, which returns an indirect reference to the new TFont object.

TFont allocates memory for the font resource, and initializes the Color property to clWindowText. TFont also initializes the PixelsPerInch property based on the screen resolution.


TFont::~TFont

TFont	See also

Destroys an instance of TFont.

__fastcall virtual ~TFont(void);

Description

Do not call ~TFont directly. Instead, use the delete keyword on the object, which causes ~TFont to be invoked automatically.

~TFont frees the resource identified by the Handle property.


Scope

Published


Hierarchy

TObject

TPersistent

TGraphicsObject


TFontAdapter

Hierarchy	Properties	Methods	See also

TFontAdapter is a helper class used to connect a TFont object to an OLE font object.

Unit

axctrls

Description

To create an instance of a TFontAdapter call the global GetOleFont procedure.  GetOleFont creates the binding between a TFont object and an OLE font interface.


TFontAdapter properties

TFontAdapter	Alphabetically	Legend

Derived from TInterfacedObject

RefCount


TFontAdapter properties

TFontAdapter	By object	Legend

RefCount


TFontAdapter methods

TFontAdapter	Alphabetically

In TFontAdapter

~TFontAdapter

Changed

TFontAdapter

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFontAdapter methods

TFontAdapter	By object

~TFontAdapter

Changed

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TFontAdapter


TFontAdapter::Changed

TFontAdapter	See also

Updates the associated IFont interface with the new properties of the font object.

virtual void __fastcall Changed(void);

Description

Changed is called automatically when the TFont object changes.  It ensures that the associated OLE interface is updated.


TFontAdapter::TFontAdapter

TFontAdapter	See also

Creates an instance of the font adapter control.

__fastcall TFontAdapter(Graphics::TFont* Font);

Description

Applications do not normally create objects of this class. Instead, they call the GetOleFont procedure, which creates the binding between a TFont and an OLE font object.


TFontAdapter::~TFontAdapter

TFontAdapter	See also

~TFontAdapter frees the memory associated with the TFontAdapter object.

__fastcall virtual ~TFontAdapter(void) { }

Description

Do not call ~TFontAdapter directly. Instead, use the delete keyword on the object, which causes ~TFontAdapter to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject

TCustomAdapter


 TFontDialog

Hierarchy	Properties	Methods	Events

TFontDialog displays a font-selection dialog.

Unit

dialogs

Description

TFontDialog displays a modal Windows dialog box for selecting fonts. The dialog does not appear at runtime until it is activated by a call to the Execute method. When the user selects a font and clicks OK, the dialog closes and the selected font is stored in the Font property.


TFontDialog properties

TFontDialog	Alphabetically	Legend

In TFontDialog

Device

Font

MaxFontSize

MinFontSize

Options

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TFontDialog properties

TFontDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DesignInfo

Device

Font

HelpContext

MaxFontSize

MinFontSize

Name

Options

Owner

Tag

VCLComObject


TFontDialog::Device

TFontDialog

Specifies the device from which to retrieve the list of available fonts.

enum TFontDialogDevice { fdScreen, fdPrinter, fdBoth };

__property TFontDialogDevice Device = {read=FDevice, write=FDevice, default=0};

Description

These are the possible values of Device:

Value	Meaning

fdScreen	Retrieve from the screen.

fdPrinter	Retrieve from the printer.

fdBoth	Retrieve from both the screen and the printer.


TFontDialog::Font

TFontDialog	See also 	Example

Indicates the selected font.

__property Graphics::TFont* Font = {read=FFont, write=SetFont};

Description

When the user selects a font in the dialog box and clicks OK, the selected font becomes the value of the Font property. To make a default font appear in the dialog when it opens, assign a value to Font in the Object Inspector or in program code.


TFontDialog::MaxFontSize

TFontDialog	See also 	Example

Determines the largest font size available in the Font dialog.

__property int MaxFontSize = {read=FMaxFontSize, write=FMaxFontSize, nodefault};

Description

Assign a value to MaxFontSize to limit the font sizes available in the dialog.

Note:	MaxFontSize is inoperative unless the fdLimitSize flag is set in Options.


TFontDialog::MinFontSize

TFontDialog	See also 	Example

Determines the smallest font size available in the Font dialog.

__property int MinFontSize = {read=FMinFontSize, write=FMinFontSize, nodefault};

Description

Assign a value to MinFontSize to limit the font sizes available in the dialog.

Note:	MinFontSize is inoperative unless the fdLimitSize flag is set in Options.


TFontDialog::Options

TFontDialog	See also 	Example

Determines the appearance and behavior of the Font dialog.

enum TFontDialogOption { fdAnsiOnly, fdTrueTypeOnly, fdEffects, fdFixedPitchOnly, fdForceFontExist, fdNoFaceSel, fdNoOEMFonts, fdNoSimulations, fdNoSizeSel, fdNoStyleSel, fdNoVectorFonts, fdShowHelp, fdWysiwyg, fdLimitSize, fdScalableOnly, fdApplyButton };

typedef Set<TFontDialogOption, fdAnsiOnly, fdApplyButton> TFontDialogOptions;

__property TFontDialogOptions Options = {read=FOptions, write=FOptions, default=4};

Description

Use the Options property to customize the appearance and functionality of the dialog. The possible values of Options are:

Value	Meaning

fdAnsiOnly	Displays only fonts that use the Windows character set. Symbol fonts are not listed in the dialog.

fdApplyButton	Displays an Apply button in the dialog, whether or not there is an OnApply event handler.

fdEffects	Displays the Effects check boxes (Strikeout and Underline) and the Color list box in the dialog.

fdFixedPitchOnly	Displays only monospaced fonts in the dialog. Proportionally spaced fonts are not listed, nor are TrueType fonts that do not have the fixed-pitch flag set in the style header.

fdForceFontExist	Allows the user to enter only fonts that are displayed in the dialog (that is, listed in the Font combo box). If the user tries to enter another font name, an error message appears.

fdLimitSize	Enables the MaxFontSize and MinFontSize properties, limiting the range of font sizes that appear in the dialog if these properties have values.

fdNoFaceSel	Causes the dialog to open without a preselected font name in the Font combo box.

fdNoOEMFonts	Removes OEM fonts from the dialog’s combo box. Lists only non-OEM fonts.

fdScalableOnly	Displays only scalable fonts in the dialog. Non-scalable (bitmap) fonts are removed from the list.

fdNoSimulations	Displays only fonts and font styles that are directly supported by the font definition file. GDI-synthesized bold and italic styles (for bitmap fonts) are not listed.

fdNoSizeSel	Causes the dialog to open without a preselected size in the Size combo box.

fdNoStyleSel	Causes the dialog to open without a preselected style in the Font Style combo box.

fdNoVectorFonts	Removes vector fonts from the dialog’s combo box; lists only non-vector fonts. (Vector fonts are Windows 1.0 fonts, such as Roman or Script, which resemble pen-plotter output.)

fdShowHelp	Displays a Help button in the dialog.

fdTrueTypeOnly	Displays only TrueType fonts in the dialog. Other fonts are not listed.

fdWysiwyg	Displays only fonts that are available to both the printer and the screen. Device-specific fonts are not listed in the dialog.

By default, all options except fdEffects are off.


TFontDialog events

TFontDialog	Alphabetically	Legend

In TFontDialog

OnApply

Derived from TCommonDialog

OnClose

OnShow


TFontDialog events

TFontDialog	By object	Legend

OnApply

OnClose

OnShow


TFontDialog::OnApply

TFontDialog	See also 	Example

Occurs when the user clicks the Apply button.

typedef void __fastcall (__closure *TFDApplyEvent)(System::TObject* Sender, HWND Wnd);

__property TFDApplyEvent OnApply = {read=FOnApply, write=FOnApply};

Description

The Apply button appears in the dialog if an event handler is assigned to OnApply or if the fdApplyButton flag is set in Options. Use an OnApply event handler to apply the selected font without closing the Font dialog box.

Note:	The Wnd parameter is the Font dialog’s window handle. Wnd has the same value as the Handle property and is maintained for backward compatibility.


TFontDialog methods

TFontDialog	Alphabetically

In TFontDialog

~TFontDialog

Execute

TFontDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TFontDialog methods

TFontDialog	By object

~TFontDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TFontDialog


TFontDialog::TFontDialog

TFontDialog 	See also

Creates and initializes a TFontDialog instance.

__fastcall virtual TFontDialog(Classes::TComponent* AOwner);

Description

Do not call TFontDialog directly. Instead, use the keyword new, which returns an indirect reference to the new Font dialog. TFontDialog objects placed on a form at design time are created automatically.

The TFontDialog method generates a TFontDialog instance, but the new dialog does not appear on the form at runtime until the Execute method is called.


TFontDialog::~TFontDialog

TFontDialog	See also

Destroys the TFontDialog and frees its memory.

__fastcall virtual ~TFontDialog(void);

Description

Do not call ~TFontDialog directly. Instead, use the delete keyword on the object, which causes ~TFontDialog to be invoked automatically.


TFontDialog::Execute

TFontDialog 	Example

Displays the Font dialog.

virtual bool __fastcall Execute(void);

Description

Execute opens the Font dialog, returning true when the user selects a font and clicks OK.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog


TForm

Hierarchy	Properties	Methods	Events	See also

TForm is the component for a standard application window (form).

Unit

forms

Description

Use TForm to create a form, such as a main window, dialog box, or MDI child. The form can contain other objects, such as TButton, TCheckBox, and TComboBox objects.

Examples of forms include TLoginDialog and TPasswordDialog objects.


TForm properties

TForm	Alphabetically	Legend

Derived from TCustomForm

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

BorderIcons

BorderStyle

Canvas

ClientHandle

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

FormStyle

HelpFile

Icon

KeyPreview

MDIChildCount

MDIChildren

Menu

ModalResult

ObjectMenuItem

OleFormObject

Parent

PixelsPerInch

Position

PrintScale

Scaled

TileMode

Visible

WindowMenu

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TForm properties

TForm	By object	Legend

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

Align

AutoScroll

BorderIcons

BorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHandle

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

FormStyle

Handle

Height

HelpContext

HelpFile

Hint

HorzScrollBar

Icon

KeyPreview

Left

MDIChildCount

MDIChildren

Menu

ModalResult

Name

ObjectMenuItem

OleFormObject

Owner

Parent

ParentFont

ParentWindow

PixelsPerInch

PopupMenu

Position

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

TileMode

Top

VCLComObject

VertScrollBar

Visible

Width

WindowMenu

WindowProc

WindowState


TForm events

TForm	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnClose

OnCloseQuery

OnCreate

OnDeactivate

OnDestroy

OnHelp

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TForm events

TForm	By object	Legend

OnActivate

OnClick

OnClose

OnCloseQuery

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHelp

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TForm methods

TForm	Alphabetically

In TForm

~TForm

ArrangeIcons

Cascade

Next

Previous

TForm

Tile

Derived from TCustomForm

Close

CloseQuery

DefocusControl

FocusControl

GetFormImage

Hide

Print

Release

SendCancelMode

SetFocus

SetFocusedControl

Show

ShowModal

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TForm methods

TForm	By object

~TForm

ArrangeIcons

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Cascade

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

DefaultHandler

DefocusControl

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Next

PaintTo

Perform

Previous

Print

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetFocus

SetFocusedControl

SetTextBuf

Show

ShowModal

TForm

Tile

Update

UpdateControlState


TForm::ArrangeIcons

TForm	See also 	Example

Arranges the icons of minimized MDI child forms.

void __fastcall ArrangeIcons(void);

Description

Use ArrangeIcons to arrange the icons of minimized MDI child forms so they are evenly spaced and don't overlap.

ArrangeIcons works only if the form is an MDI parent form (that is, if the form’s FormStyle property is fsMDIForm).


TForm::Cascade

TForm	See also 	Example

Arranges MDI child forms so they overlap.

void __fastcall Cascade(void);

Description

Use Cascade to arrange MDI child forms so they overlap.

Cascade works only if the form is an MDI parent form (that is, if the form’s FormStyle property is fsMDIForm).


TForm::Next

TForm	See also	Example

Activates the next child form in the form sequence.

void __fastcall Next(void);

Description

Use Next to change the active child form of an MDI parent. For example, if you have three child forms within a parent form and Form2 is the active form, the Next method makes Form3 the active form. Calling Next again makes Form4 active. The next time your application calls Next, the sequence starts over again and Form2 becomes the active form once again.

The Next method applies only to forms that are MDI parent forms (have a FormStyle property value of fsMDIForm).


TForm::Previous

TForm	See also	Example

Activates the previous MDI child form in the form sequence.

void __fastcall Previous(void);

Description

Use Previous to change the active child form of an MDI parent. For example, if you have three child forms within a parent form and Form4 is the active form, the Previous method makes Form3 the active form. Calling Previous again makes Form2 active. The next time your application calls Previous, the sequence starts over again and Form4 becomes the active form once again.

The Previous method applies only to forms that are MDI parent forms (have a FormStyle property value of fsMDIForm).


TForm::Tile

TForm	See also	Example

Arranges MDI child forms so that they are all the same size.

void __fastcall Tile(void);

Description

Use Tile to arrange MDI child forms so that they are all the same size. Tiled forms completely fill up the client area of the parent form. How the forms arrange themselves depends upon the values of their TileMode properties.

Tile works only if the form is an MDI parent form (that is, if the form’s FormStyle property is fsMDIForm).


TForm::TForm

TForm

Creates a new TForm object.

__fastcall virtual TForm(Classes::TComponent* AOwner) : Forms::TCustomForm(AOwner) { }

__fastcall TForm(Classes::TComponent* AOwner, int Dummy) : Forms::TCustomForm(AOwner, Dummy) { }

__fastcall TForm(HWND ParentWindow) : Forms::TCustomForm(ParentWindow) { }

Description

Call TForm indirectly, using the new keyword, to create a new form object at runtime. Forms added to an application at design time are created automatically.

Pass a single Component as a parameter to provide the form with an Owner (usually the application) that is responsible for freeing it. This is the most commonly used constructor syntax.

Pass a Component and an integer to create the form while bypassing the streaming system that loads a form’s properties and descendants from a .DFM file. The second parameter (Dummy) serves only to distinguish this constructor from the first. This constructor is rarely used for form objects. When using this syntax, stream in an external .DFM to bind the visual components with their classes. WriteComponentResFile and ReadComponentResFile must bracket the constructor call. The following code sequence

1.	streams-out an external .DFM file

2.	creates a new form disassociated from any .DFM resource file

3.	streams-in the external .DFM file and binds it to this new form:

WriteComponentResFile("Temp.dfm", Form1);

…

Form2 = new TForm(Application,1);

ReadComponentResFile("Temp.dfm", Form2);

Pass a window handle as a parameter to embed the form in a non-VCL window. This syntax is used when the form is implemented as an ActiveX control that is embedded in a non-VCL window.


TForm::~TForm

TForm

Frees the memory associated with the TForm object.

__fastcall virtual ~TForm(void) { }

Description

Do not call ~TForm directly. Instead, use the delete keyword on the object, which causes ~TForm to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm


TFormDesigner

Hierarchy	Properties	Methods

TFormDesigner is an abstract type from which the form designer in C++Builder descends.

Unit

dsgnintf

Description

Use TFormDesigner to interact with the current source when implementing a property editor or component editor. Obtain an instance of a descendant of TFormDesigner through the Designer property of the property editor or component editor. TFormDesigner introduces several methods that are useful for creating and manipulating components and methods such as event handlers.


TFormDesigner properties

TFormDesigner	Alphabetically	Legend

In TFormDesigner

IsDormant

Derived from TDesigner

Form

IsControl


TFormDesigner properties

TFormDesigner	By object 	Legend

Form

IsControl

IsDormant


TFormDesigner::IsDormant

TFormDesigner 	See also

Indicates whether the current root object exists in the IDE or is only available as a streamed-out memory image.

__property bool IsDormant = {read=GetIsDormant, nodefault};

Description

Component writers should not need to use the IsDormant property, which should always be false when property editors or component editors are up. IsDormant is used internally when loading and unloading packages.


TFormDesigner methods

TFormDesigner	Alphabetically

In TFormDesigner

~TFormDesigner

AddToInterface

CreateComponent

CreateMethod

GetComponent

GetComponentName

GetComponentNames

GetIsDormant

GetMethodName

GetMethods

GetObject

GetObjectName

GetObjectNames

GetPrivateDirectory

GetProjectModules

GetRoot

GetSelections

HasInterface

HasInterfaceMember

IsComponentLinkable

MakeComponentLinkable

MethodExists

MethodFromAncestor

RenameMethod

Revert

SelectComponent

SetSelections

ShowMethod

TFormDesigner

UniqueName

Derived from TDesigner

IsDesignMsg

Modified

Notification

PaintGrid

ValidateRename

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TFormDesigner methods

TFormDesigner	By object

~TFormDesigner

AddToInterface

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComponent

CreateMethod

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetComponent

GetComponentName

GetComponentNames

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetIsDormant

GetMethodName

GetMethods

GetObject

GetObjectName

GetObjectNames

GetPrivateDirectory

GetProjectModules

GetRoot

GetSelections

HasInterface

HasInterfaceMember

InheritsFrom

InitInstance

InstanceSize

IsComponentLinkable

IsDesignMsg

MakeComponentLinkable

MethodAddress

MethodExists

MethodFromAncestor

MethodName

Modified

NewInstance

Notification

PaintGrid

RenameMethod

Revert

SafeCallException

SelectComponent

SetSelections

ShowMethod

TFormDesigner

UniqueName

ValidateRename


TFormDesigner::AddToInterface

TFormDesigner 	See also

Introduces the abstract prototype of a method that adds a new property or method to the root object’s interface.

virtual void __fastcall AddToInterface(int InvKind, const System::AnsiString Name, Word VT, const System::AnsiString TypeInfo) = 0;

Description

Use AddToInterface to define a new procedure, function, or property for the interface of a remote data module or active form.

The InvKind parameter specifies the type of interface to add. It is of the following values:

Value	Meaning

INVOKE_FUNC	The interface member calls a method.

INVOKE_PROPERTYGET	The interface member returns a property value.

INVOKE_PROPERTYPUT	The interface member sets a property value.

INVOKE_PROPERTYPUTREF	The interface member sets a property by reference.

The Name parameter specifies the name of the property or method.

The T parameter indicates the return type of the interface member.  It is a VARENUM value such as VT_BOOL (bool), VT_DISPATCH (IDISPATCH pointer), VTERROR (SCODE), and so on.

The TypeInfo parameter gives the name of the typeinfo of the return type if the T parameter is VT_USERDEFINED.  The typeinfo is the same value that defines the type in the type library.


TFormDesigner::TFormDesigner
TFormDesigner::CreateComponent

TFormDesigner 	See also

Introduces the abstract prototype of a method that creates a specified component.

virtual Classes::TComponent* __fastcall CreateComponent(System::TMetaClass* ComponentClass, Classes::TComponent* Parent, int Left, int Top, int Width, int Height) = 0;

Description

Call CreateComponent to create an instance of ComponentClass at the position specified by the Left and Height parameters with the size specified by the Width and Height parameters. The new component will be a child of the component specified by the Parent parameter.


TFormDesigner::TFormDesigner
TFormDesigner::CreateMethod

TFormDesigner 	See also

Introduces the abstract prototype of a method that creates an event handler.

struct TMethod

{

  void *Code;

  void *Data;

} ;

virtual Sysutils::TMethod __fastcall CreateMethod(const System::AnsiString Name, Typinfo::PTypeData TypeData) = 0;

Description

Call CreateMethod to add an event handler to the source file of the object returned by the GetRoot method. Allocate a TTypeData structure and fill in the MethodKind, ParamCount, and ParamList fields. The event handler gets the name specified by the Name parameter and the type specified by the TypeData parameter. CreateMethod returns a method pointer to the new event handler.


TFormDesigner::GetComponent

TFormDesigner 	See also

Introduces the abstract prototype for a method that returns the component with the name passed as a parameter.

virtual Classes::TComponent* __fastcall GetComponent(const System::AnsiString Name) = 0;

Description

Call GetComponent to access a component given its name. If the component is not in the current root object, the Name parameter should include the name of the entity in which it resides. For example, to obtain a reference to a component in a data module named "DataModule2 ", use a line such as

TheComponent = Designer->GetComponent("DataModule2.Button1");

If DataModule2’s header included in the source file of the current root object, GetComponent will return the component.

Note:	To obtain a reference to a persistent object that is not a component, use the GetObject method instead.


TFormDesigner::GetComponentName

TFormDesigner 	See also

Introduces the abstract prototype of a method that returns the name of the component passed as its parameter.

virtual System::AnsiString __fastcall GetComponentName(Classes::TComponent* Component) = 0;

Description

Call GetComponentName to obtain the name of a component. This is the inverse of GetComponent.

Note:	If the component is in the current root object, GetComponentName returns the Name property of the component itself. If the component is in another entity, GetComponentName qualifies the component name with the name of the object in which it resides.


TFormDesigner::GetComponentNames

TFormDesigner 	See also

Introduces the abstract prototype of a method that implements a callback for every component that can be assigned a property of a specified type.

typedef void __fastcall (__closure *TGetStrProc)(const System::AnsiString S);

virtual void __fastcall GetComponentNames(Typinfo::PTypeData TypeData, Classes::TGetStrProc &Proc) = 0;

Description

Use GetComponentNames to call the procedure specified by the Proc parameter for every component that can be assigned a property that matches the TypeData parameter. For each component, Proc is called with its S parameter set to the name of the component. This parameter can be used to obtain a reference to the component by calling the GetComponent method.

Note:	GetComponentNames will call the Proc parameter for components in source files whose headers are included by the current root object’s source file as well as the entity returned by the GetRoot method.


TFormDesigner::GetIsDormant

TFormDesigner 	See also

Introduces the abstract prototype of a method that implements the read-only IsDormant property.

virtual bool __fastcall GetIsDormant(void) = 0;

Description

Do not use the GetIsDormant method. It is overridden in descendants of TFormDesigner to implement the IsDormant property.


TFormDesigner::GetMethodName

TFormDesigner 	See also

Introduces the abstract prototype of a method that returns the name of a specified event handler.

struct TMethod

{

  void *Code;

  void *Data;

} ;

virtual System::AnsiString __fastcall GetMethodName(const Sysutils::TMethod &Method) = 0;

Description

Call GetMethodName to obtain the name of an event handler given a pointer to it.


TFormDesigner::GetMethods

TFormDesigner 	See also

Introduces the abstract prototype of a method that implements a callback for every method of a specified type.

virtual void __fastcall GetMethods(Typinfo::PTypeData TypeData, Classes::TGetStrProc &Proc) = 0;

Description

Use GetMethods to call the procedure specified by the Proc parameter for every event handler that matches the TypeData parameter. For each event handler, Proc is called with its S parameter set to the name of the method. This parameter can be used to bring up a code editor for the method by calling the ShowMethod method.


TFormDesigner::GetObject

TFormDesigner 	See also

Introduces the abstract prototype for a method that returns the persistent object with the name passed as a parameter.

virtual Classes::TPersistent* __fastcall GetObject(const System::AnsiString Name) = 0;

Description

Call GetObject to access a persistent object given its name. This is useful when working with components that include constituent objects such as the TStatusPanel objects that are used by TStatusBar.

To obtain the name of a persistent object, use the GetObjectName method.


TFormDesigner::GetObjectName

TFormDesigner 	See also

Introduces the abstract prototype of a method that returns the name of the object passed as its parameter.

virtual System::AnsiString __fastcall GetObjectName(Classes::TPersistent* Instance) = 0;

Description

Call GetObjectName to obtain the name of a persistent object. This is the inverse of GetObject. GetObjectName is useful when working with components that include constituent objects, such as the TStatusPanel objects that are used by TStatusBar.


TFormDesigner::GetObjectNames

TFormDesigner 	See also

Introduces the abstract prototype of a method that implements a callback for every object that can be assigned a property of a specified type.

typedef void __fastcall (__closure *TGetStrProc)(const System::AnsiString S);

virtual void __fastcall GetObjectNames(Typinfo::PTypeData TypeData, Classes::TGetStrProc &Proc) = 0;

Description

Use GetObjectNames to call the procedure specified by the Proc parameter for every persistent object that can be assigned a property that matches the TypeData parameter. For each object, Proc is called with its S parameter set to the name of the object. This parameter can be used to obtain a reference to the object by calling the GetObject method.

Note:	GetObjectNames will call the Proc parameter for components in forms or modules whose header files are included by the current root object’s source file as well as the entity returned by the GetRoot method.


TFormDesigner::GetPrivateDirectory

TFormDesigner

Introduces the abstract prototype of a method that returns the private directory for the form designer.

virtual System::AnsiString __fastcall GetPrivateDirectory(void) = 0;

Description

Call GetPrivateDirectory to obtain the location specified in the registry under the key:

HKEY_CURRENT_USER\Software\Borland\CBuilder\3.0\Globals\PrivateDir

This directory can be used for housing executables or auxiliary files that store state information, examples, templates, and so on.


TFormDesigner::GetProjectModules

TFormDesigner 	See also

Introduces the abstract prototype of a method that allows access to project-specific information.

typedef void __fastcall (__closure *TGetModuleProc)(const System::AnsiString FileName, const System::AnsiString UnitName, const System::AnsiString FormName, const System::AnsiString DesignClass, TStrings* CoClasses);

virtual void __fastcall GetProjectModules(Classes::TGetModuleProc &Proc) = 0;

Description

Call GetProjectModules to execute a callback function for every module in the current project. The callback is of type TGetModuleProc.

The FileName parameter specifies the file name for the module.  The UnitName parameter specifies the name of the unit (usually the same as the file base name).  The FormName parameter indicates the name of the associated form, data module, property page, or other registered base component.  The DesignClass parameter indicates the class of the object named by the FormName parameter.  The CoClasses parameter lists all CoClasses supported by the module.

Use GetProjectModules to obtain information about other root components in the project besides the current root component returned by the GetRoot method.


TFormDesigner::GetRoot

TFormDesigner 	See also

Introduces the abstract prototype for a method that returns the current entity being edited by the form designer.

virtual Classes::TComponent* __fastcall GetRoot(void) = 0;

Description

Call GetRoot to obtain the object the form designer is working on. If this object is a descendant of TCustomForm, GetRoot returns the value of the Form property.

Use GetRoot rather than the Form property, to ensure that code works even when editing a data module, remote data module, active form, or other registered base component that is not a descendant of TCustomForm.


TFormDesigner::GetSelections

TFormDesigner 	See also

Introduces the abstract prototype for a method that returns all selected components on the current root object.

virtual void __fastcall GetSelections(TComponentList* List) = 0;

Description

Use GetSelections to access every component currently selected on the root object returned by the GetRoot method.

Note:	The list returned by GetSelections can hold persistent objects that are not components, as well as components.


TFormDesigner::HasInterface

TFormDesigner 	See also

Introduces the abstract prototype for a method that indicates whether the current root object has an associated interface.

virtual bool __fastcall HasInterface(void) = 0;

Description

Call HasInterface to determine whether the designer is working on an entity with an associated interface, such as a remote data module or active form. If HasInterface returns true, then the HasInterfaceMember and AddInterfaceMember methods can be used.


TFormDesigner::HasInterfaceMember

TFormDesigner 	See also

Introduces the abstract prototype for a method that indicates whether the interface associated with the current root object has a specified property or method.

virtual bool __fastcall HasInterfaceMember(const System::AnsiString Name) = 0;

Description

Call HasInterfaceMember to determine whether the interface of the current root object has a property or method with the name specified by the Name parameter.

Note:	If the object returned by the GetRoot method does not have an associated interface, then HasInterfaceMember always returns false.


TFormDesigner::IsComponentLinkable

TFormDesigner 	See also

Introduces the abstract prototype for a method that indicates whether a component is declared in the header of the current root object.

virtual bool __fastcall IsComponentLinkable(Classes::TComponent* Component) = 0;

Description

Call IsComponentLinkable to determine whether the component specified by the Component parameter can be referenced from within the object returned by the GetRoot method. IsComponentLinkable returns true if the specified component is declared in the source file of the root object of one of the headers it includes.

If IsComponentLinkable returns false, the component’s header can be included in the source file of the root unit by calling MakeComponentLinkable.


TFormDesigner::MakeComponentLinkable

TFormDesigner 	See also

Introduces the abstract prototype for a method that adds a component’s header to the source file of the root unit.

virtual void __fastcall MakeComponentLinkable(Classes::TComponent* Component) = 0;

Description

Call MakeComponentLinkable to include the specified component's header in the source file of the object being designed.


TFormDesigner::MethodExists

TFormDesigner 	See also

Introduces the abstract prototype for a method that indicates whether an event handler with a specified name already exists.

virtual bool __fastcall MethodExists(const System::AnsiString Name) = 0;

Description

Call MethodExists to determine whether an event handler with a given name has already been created. If MethodExists returns true, the specified event handler exists and can be displayed by calling the ShowMethod method. If MethodExists returns false, the specified event handler does not exist, and can be created by calling the CreateMethod method.


TFormDesigner::MethodFromAncestor

TFormDesigner 	See also

Introduces the abstract prototype for a method that indicates whether an event handler is inherited from an ancestor of the root object.

struct TMethod

{

  void *Code;

  void *Data;

} ;

virtual bool __fastcall MethodFromAncestor(const Sysutils::TMethod &Method) = 0;

Description

Call MethodFromAncestor to determine whether a given method is implemented by the object returned from the GetRoot method. MethodFromAncestor returns false if the method is introduced by the root object, true if it is introduced by an ancestor.


TFormDesigner::RenameMethod

TFormDesigner 	See also

Introduces the abstract prototype for a method that renames an existing event handler.

virtual void __fastcall RenameMethod(const System::AnsiString CurName, const System::AnsiString NewName) = 0;

Description

Call RenameMethod to provide an event handler with a new name. The CurName parameter specifies the current name of the event handler, and the NewName parameter specifies the value that the name should be changed to.

Note:	Before calling RenameMethod, check whether a method with the new name already exists by calling MethodExists.


TFormDesigner::Revert

TFormDesigner 	See also

Introduces the abstract prototype for a method that restores a specified property to its value before any edits were made.

virtual void __fastcall Revert(Classes::TPersistent* Instance, Typinfo::PPropInfo PropInfo) = 0;

Description

Call Revert to undo all changes that have been made to the property specified by the PropInfo parameter on the object specified by the Instance parameter. Revert restores the property to the setting it had when Instance was first created.


TFormDesigner::SelectComponent

TFormDesigner 	See also

Introduces the abstract prototype for a method that replaces the current set of selected components by a single specified object.

virtual void __fastcall SelectComponent(Classes::TPersistent* Instance) = 0;

Description

Call SelectComponent to select a single persistent object in the designer. Any previous set of selected components are de-selected. To select a set of objects, use the SetSelections method instead.


TFormDesigner::SetSelections

TFormDesigner 	See also

Introduces the abstract prototype for a method that changes the currently selected set of components.

virtual void __fastcall SetSelections(TComponentList* List) = 0;

Description

Call SetSelections to programmatically change which objects in the root object are selected.

Note:	The List parameter of SetSelections can contain persistent objects that are not components.


TFormDesigner::ShowMethod

TFormDesigner 	See also

Introduces the abstract prototype for a method that activates the code editor with the input cursor in a specified event handler.

virtual void __fastcall ShowMethod(const System::AnsiString Name) = 0;

Description

Call ShowMethod to allow the user to edit the method specified by the Name parameter.


TFormDesigner::UniqueName

TFormDesigner 	See also

Introduces the abstract prototype for a method that generates a unique name from a specified base string.

virtual System::AnsiString __fastcall UniqueName(const System::AnsiString BaseName) = 0;

Description

Call UniqueName to automatically generate a unique name for a component Specify the base string for the name by the BaseName parameter. UniqueName will append a number to BaseName to ensure that there are no name-space conflicts.


TFormDesigner::TFormDesigner

TFormDesigner

Creates a new TFormDesigner object.

__fastcall TFormDesigner(void) : Forms::TDesigner() { }

Description

Do not create instances of TFormDesigner, which contains pure virtual methods. Form designers are created automatically by the IDE when a new form, data module, or other registered base component is created at design time.


TFormDesigner::~TFormDesigner

TFormDesigner

Frees the memory associated with the TFormDesigner object.

__fastcall virtual ~TFormDesigner(void) { }

Description

Do not use the destructor for TFormDesigner. Form designers are automatically deleted by the IDE when they are no longer needed.


Accessibility

Read-only


Hierarchy

TObject

TDesigner


TGraphicField

Hierarchy	Properties	Methods	Events	See also

TGraphicField represents a graphics field in a dataset.

Unit

db

Description

Graphics fields are a form of binary large object (BLOB) field where the data includes a BLOB header describing the encoding of the graphical value. TGraphicField differs from its immediate ancestor TBlobField only in having a DataType of ftGraphic. As a descendant of TBlobField, TGraphicField includes many properties, methods, and events that are useful for managing the value and properties of a BLOB field in a database.


TGraphicField properties

TGraphicField	Alphabetically	Legend

Derived from TBlobField

AsString

AsVariant

BlobSize

BlobType

IsNull

Modified

Transliterate

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TGraphicField properties

TGraphicField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

BlobSize

BlobType

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Modified

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

Transliterate

ValidChars

Value

VCLComObject

Visible


TGraphicField events

TGraphicField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TGraphicField events

TGraphicField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TGraphicField methods

TGraphicField	Alphabetically

In TGraphicField

~TGraphicField

TGraphicField

Derived from TBlobField

Assign

Clear

IsBlob

LoadFromFile

LoadFromStream

SaveToFile

SaveToStream

SetFieldType

SetText

Derived from TField

AssignValue

FocusControl

GetData

IsValidChar

RefreshLookupList

SetData

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TGraphicField methods

TGraphicField	By object

~TGraphicField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SaveToFile

SaveToStream

SetData

SetFieldType

SetText

TGraphicField

Validate


TGraphicField::TGraphicField

TGraphicField	See also

Creates an instance of TGraphicField.

__fastcall virtual TGraphicField(Classes::TComponent* AOwner);

Description

TGraphicField creates and initializes an instance of TGraphicField. After calling the parent class’s constructor, TGraphicField sets the DataType to ftGraphic.

Applications seldom need to create TGraphicField objects because a graphic field component is instantiated automatically for all graphic fields in a dataset. When creating a graphic field, use the new keyword.


TGraphicField::~TGraphicField

TGraphicField

Frees the memory associated with the TGraphicField object.

__fastcall virtual ~TGraphicField(void) { }

Description

Do not call ~TGraphicField directly. Instead, use the delete keyword on the object, which causes ~TGraphicField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TBlobField


TGraphic

Hierarchy	Properties	Methods	Events	See also

TGraphic is the abstract base class type for objects such as icons, bitmaps, and metafiles that can store and display visual images.

Unit

graphics

Description

TGraphic is an abstract class that cannot be instantiated. Descendant graphics objects override many of the methods of TGraphic to address the needs of their particular file format and graphical characteristics. TGraphic also introduces methods that work with TPicture objects and the Clipboard. Properties of TGraphic provide information about the state and size of the graphic image.

When the type of graphic (bitmap, icon, or metafile) is known, store the graphic in its specific type object (TBitmap, TIcon, or TMetafile, respectively). Otherwise, use a TPicture object that can hold any type of TGraphic.


TGraphic properties

TGraphic	Alphabetically	Legend

In TGraphic

Empty

Height

Modified

Palette

PaletteModified

Transparent

Width


TGraphic properties

TGraphic	By object	Legend

Empty

Height

Modified

Palette

PaletteModified

Transparent

Width


TGraphic::Empty

TGraphic 	Example

Indicates whether the graphics object contains a graphic.

__property bool Empty = {read=GetEmpty, nodefault};

Description

Each descendant graphic object defines its own Get method to access the Empty property.


TGraphic::Height

TGraphic

Specifies the vertical size of the graphic in pixels.

__property int Height = {read=GetHeight, write=SetHeight, nodefault};

Description

Each descendant graphic object defines its own Get and Set methods to access the Height property.


TGraphic::Modified

TGraphic

Indicates whether the graphics object has been changed or edited.

__property bool Modified = {read=FModified, write=SetModified, nodefault};

Description

If Modified is true, the graphics object has changed. If Modified is false, the graphics object is in the same state as when the object was loaded.

The Modified property indicates only if bitmap objects have been modified. Modified is not true if the graphics object contains an icon or metafile graphic, even if they have been modified.

If the graphics object was modified, save the changes to a file with the SaveToFile method. The next time the application runs, it can load the graphic from the file with the LoadFromFile method.


TGraphic::Palette

TGraphic

Indicates the color palette of the graphical image.

__property HPALETTE Palette = {read=GetPalette, write=SetPalette, nodefault};

Description

Use Palette to get the color palette of a graphical image. If the graphic does not need or does not use a palette, the Palette property is zero.


TGraphic::PaletteModified

TGraphic

Indicates whether the palette has changed.

__property bool PaletteModified = {read=FPaletteModified, write=FPaletteModified, nodefault};

Description

Use PaletteModified to determine if the palette used for a graphical image has changed. PaletteModified is used in the OnChange event. PaletteModified remains true until whoever's responsible for realizing this new palette (for example, TImage) sets it to false.


TGraphic::Transparent

TGraphic 	Example

Indicates whether the image covers its rectangular area.

__property bool Transparent = {read=GetTransparent, write=SetTransparent, nodefault};

Description

Use Transparent to specify that the graphic be drawn transparently. Some descendants of TGraphic such as TIcon and TMetafile are always transparent, so setting the property for those objects does not change their behavior. However, the TBitmap graphic's drawing is affected by this property. The TImage component sets this property to be the same as its Transparent property to achieve transparent painting.


TGraphic::Width

TGraphic

Determines the maximum width of the graphics object in pixels.

__property int Width = {read=GetWidth, write=SetWidth, nodefault};

Description

Each descendant graphic object defines its own Get and Set methods to access the Width property.


TGraphic events

TGraphic	Alphabetically

In TGraphic

OnChange

OnProgress


TGraphic events

TGraphic	By object

OnChange

OnProgress


TGraphic::OnChange

TGraphic

Occurs whenever a graphical image changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Use OnChange to write a handler to perform an action then the graphical image changes.


TGraphic::OnProgress

TGraphic	See also

Occurs when a graphical image is in the process of changing.

__property TProgressEvent OnProgress = {read=FOnProgress, write=FOnProgress};

Description

For certain descendants of TGraphic, OnProgress occurs during slow processes such as loading, storing, or transforming image data. OnProgress allows applications to provide feedback to the user about the progress of the slow process.

Component writers can generate OnProgress events for new descendants of TGraphic by calling the protected Progress method. These events are propagated to the TPicture and TImage objects.

The Stage parameter indicates whether the operation is beginning, continuing, or ending. If the OnProgress event handler displays an indicator such as a progress bar, the indicator can be created when Stage is psStarting, updated while Stage is psRunning, and removed when Stage is psEnding. The PercentDone parameter is an approximation of how much of the operation has completed. Use PercentDone to update the position of a progress bar or other indicator.

The RedrawNow parameter indicates whether the image can safely be drawn on screen at this point. The R parameter specifies the portion of the image that has changed and needs to be redrawn.

The Msg parameter contains one or two words that describe what operation is occurring. For example, the value of Msg could be a string such as Loading, Storing, or Reducing colors. The Msg string can also be empty.


TGraphic methods

TGraphic	Alphabetically

In TGraphic

~TGraphic

LoadFromClipboardFormat

LoadFromFile

LoadFromStream

SaveToClipboardFormat

SaveToFile

SaveToStream

TGraphic

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TGraphic methods

TGraphic	By object

~TGraphic

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromClipboardFormat

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

SafeCallException

SaveToClipboardFormat

SaveToFile

SaveToStream

TGraphic


TGraphic::LoadFromClipboardFormat

TGraphic	See also

Introduces an abstract method that loads the image from a variable in Clipboard format.

virtual void __fastcall LoadFromClipboardFormat(Word AFormat, int AData, HPALETTE APalette) = 0;

Description

Each descendant graphic object defines a LoadFromClipboardFormat method that replaces the current graphic image with the graphic indicated by AData, which it loads from the Clipboard.

The format for the new graphic object must be registered with the Clipboard in the RegisterClipboardFormat method, or an exception is raised.


TGraphic::LoadFromFile

TGraphic 	See also	Example

Loads a graphic image stored in a file.

virtual void __fastcall LoadFromFile(const System::AnsiString Filename);

Description

LoadFromFile reads the file specified in Filename and loads the data into the graphics object.


TGraphic::LoadFromStream

TGraphic 	See also

Introduces an abstract method that loads the image from a stream.

virtual void __fastcall LoadFromStream(Classes::TStream* Stream) = 0;

Description

Each descendant graphic object defines a LoadFromStream method that loads a graphics object from Stream.


TGraphic::SaveToClipboardFormat

TGraphic	See also

Introduces an abstract method that assigns the graphic to a variable in clipboard format.

virtual void __fastcall SaveToClipboardFormat(Word &AFormat, int &AData, HPALETTE &APalette) = 0;

Description

Each descendant graphic object defines a SaveToClipboardFormat method that saves that particular graphic image type to a Clipboard format. An application must have registered the format with the TGraphic object using the RegisterClipboardFormat method.


TGraphic::SaveToFile

TGraphic

Saves a graphics image to a file.

virtual void __fastcall SaveToFile(const System::AnsiString Filename);

Description

SaveToFile writes the graphic to a file, specified by Filename.


TGraphic::SaveToStream

TGraphic

Introduces an abstract method that saves the graphic image to a stream.

virtual void __fastcall SaveToStream(Classes::TStream* Stream) = 0;

Description

Each descendant graphic object defines a SaveToStream method that saves a the object to a Stream.


TGraphic::TGraphic

TGraphic

Creates a new TGraphic object.

__fastcall virtual TGraphic(void);

Description

Do not instantiate a TGraphic object. To add a graphic object to a form, create an instance of a TGraphic descendant using the new keyword.


TGraphic::~TGraphic

TGraphic

Frees the memory associated with the TGraphic object.

__fastcall virtual ~TGraphic(void) { }

Description

Do not call ~TGraphic directly. Instead, use the delete keyword on the object, which causes ~TGraphic to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TGraphicsObject

Hierarchy	Properties	Methods	Events	See also

TGraphicsObject is the abstract base class for objects which encapsulate a Windows graphics object: TBrush, TFont, and TPen.

Unit

graphics

Description

Create descendants of TGraphicsObject when drawing an image to a canvas (TCanvas). Each TGraphicsObject object describes a Windows graphics object that is selected into the device context of the canvas.

TGraphicsObject introduces a mechanism for responding to changes in the properties of the graphics object.


TGraphicsObject properties

TGraphicsObject	Alphabetically

In TGraphicsObject

OwnerCriticalSection


TGraphicsObject properties

TGraphicsObject	By object

OwnerCriticalSection


TGraphicsObject::OwnerCriticalSection

TGraphicsObject	See also

Points to the critical section that the canvas which draws with this graphics object uses to lock out other threads.

typedef _RTL_CRITICAL_SECTION TRTLCriticalSection;

__property Windows::PRTLCriticalSection OwnerCriticalSection = {read=FOwnerLock, write=FOwnerLock};

Description

Use OwnerCriticalSection to obtain information about the thread locking state of the canvas that draws with this graphics object. The canvas sets OwnerCriticalSection when it creates the graphics object. Do not change this property while the canvas is using the graphics object.

If the graphics object is created on behalf of a drawing surface that is not a canvas, set OwnerCriticalSection to an initialized TRTLCriticalSection that is maintained by the drawing surface.

To use OwnerCriticalSection to block other execution threads, use the Lock method.


TGraphicsObject events

TGraphicsObject	Alphabetically

In TGraphicsObject

OnChange


TGraphicsObject events

TGraphicsObject	By object

OnChange


TGraphicsObject::OnChange

TGraphicsObject	See also

Occurs immediately after the Windows graphics object changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action when the graphics object changes. The properties of the graphics object reflect the new settings when OnChange occurs.


TGraphicsObject methods

TGraphicsObject	Alphabetically	Legend

In TGraphicsObject

~TGraphicsObject

Changed

Lock

TGraphicsObject

Unlock

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TGraphicsObject methods

TGraphicsObject	By object	Legend

~TGraphicsObject

Assign

Changed

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

Lock

MethodAddress

MethodName

NewInstance

SafeCallException

TGraphicsObject

Unlock


TGraphicsObject::Changed

TGraphicsObject	See also

Generates an OnChange event when the properties of the graphics object change.

DYNAMIC void __fastcall Changed(void);

Description

Descendants of TGraphicsObject call Changed after making changes to the properties encapsulated by the TGraphicsObject object.


TGraphicsObject::Lock

TGraphicsObject	See also

Blocks other execution threads from using the associated canvas until the Unlock method is called.

void __fastcall Lock(void);

Description

Call Lock in a multithreaded application before using the graphics object in a section of code that would not otherwise be thread-safe. Lock prevents other cooperating threads in the application from using the associated canvas until the Unlock method is called. Calls to Lock can be nested so that the canvas is not unlocked until the last lock is released.

Because Lock prevents other threads from executing, it can adversely affect performance. Do not call Lock unless there is a danger that another thread might interfere with the drawing.

Note:	Lock will do nothing unless the drawing surface sets the OwnerCriticalSection property. TCanvas objects automatically set the OwnerCriticalSection property when they use graphics objects.


TGraphicsObject::Unlock

TGraphicsObject	See also

Releases the lock on execution threads set by the Lock method.

void __fastcall Unlock(void);

Description

Call Unlock at the end of a thread-sensitive section of code that was started with a call to the Lock method. When every call to Lock is balanced by a call to Unlock, other threads are allowed to lock the associated canvas.


TGraphicsObject::TGraphicsObject

TGraphicsObject

Creates a new TGraphicsObject object.

__fastcall TGraphicsObject(void) : Classes::TPersistent() { }

Description

Do not call TGraphics object directly to instantiate a graphics object.  Instead, use the new keyword.


TGraphicsObject::~TGraphicsObject

TGraphicsObject

~TGraphicsObject frees the memory associated with the TGraphicsObject object.

__fastcall virtual ~TGraphicsObject(void) { }

Description

Do not call ~TGraphicsObject directly. Instead, use the delete keyword on the object, which causes ~TGraphicsObject to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TPersistent


TGridDataLink

Hierarchy	Properties	Methods	See also

TGridDataLink helps manage the link to a data source and maintain the field mapping for a TCustomDBGrid object.

Unit

dbgrids

Description

TGridDataLink is tailored to work with a TCustomDBGrid. It should only be used by the TCustomDBGrid class.


TGridDataLink properties

TGridDataLink	Alphabetically	Legend

In TGridDataLink

DefaultFields

FieldCount

Fields

SparseMap

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TGridDataLink properties

TGridDataLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

DefaultFields

Editing

FieldCount

Fields

ReadOnly

RecordCount

SparseMap


TGridDataLink::DefaultFields

TGridDataLink	See also

Indicates whether the dataset’s underlying field components are generated dynamically when the dataset is opened.

__property bool DefaultFields = {read=GetDefaultFields, nodefault};

Description

Read DefaultFields to determine whether or not a dataset uses dynamically generated field components or persistent field components. If DefaultFields is true, the dataset uses dynamically allocated field components. If DefaultFields is false, the dataset uses persistent field components or the custom field mapping contains unmapped fields.

If DefaultFields is false, the TCustomDBGrid may not show all the fields that are present in the underlying database table.


TGridDataLink::FieldCount

TGridDataLink	See also 	Example

Indicates the number of entries in the field map.

__property int FieldCount = {read=FFieldCount, nodefault};

Description

Read FieldCount to determine the number of entries in the field map. Used with the Fields property, this is useful for applications that need to iterate over all of the mapped fields.

FieldCount is the same as the number of columns in the TCustomDBGrid. The field map can contain undefined fields, which do not appear in the dataset. Undefined fields in the field map stand in for fields in the columns of the grid that are not in the dataset, such as calculated fields.


TGridDataLink::Fields

TGridDataLink	See also	Example

Lists all the field components contained in the field map.

__property Db::TField* Fields[int I] = {read=GetFields};

Description

Use Fields to access field components by index number. Fields is a zero-based array. If the SparseMap property is true, the field map may contain undefined fields. For these entries, Fields returns NULL.


TGridDataLink::SparseMap

TGridDataLink	See also

Indicates whether the associated grid has customized the field map (which means it may contain undefined fields).

__property bool SparseMap = {read=FSparseMap, write=FSparseMap, nodefault};

Description

Read SparseMap to determine whether the field map is not a simple reflection of the underlying dataset. The TCustomDBGrid sets SparseMap when it builds the field map. SparseMap is false if the TCustomDBGrid builds a default field map directly from the dataset. Any changes to the field components associated with each column cause TCustomDBGrid to change SparseMap to true. When SparseMap is true, the field map may contain undefined fields if the column attributes indicate an invalid field name or an unassigned field component.


TGridDataLink methods

TGridDataLink	Alphabetically	Legend

In TGridDataLink

~TGridDataLink

ActiveChanged

AddMapping

ClearMapping

DataSetChanged

DataSetScrolled

EditingChanged

FocusControl

GetMappedIndex

LayoutChanged

Modified

RecordChanged

Reset

TGridDataLink

UpdateData

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TGridDataLink methods

TGridDataLink	By object	Legend

~TGridDataLink

ActiveChanged

AddMapping

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearMapping

DataSetChanged

DataSetScrolled

DefaultHandler

Dispatch

Edit

EditingChanged

FieldAddress

FocusControl

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMappedIndex

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LayoutChanged

MethodAddress

MethodName

Modified

NewInstance

RecordChanged

Reset

SafeCallException

TGridDataLink

UpdateData

UpdateRecord


TGridDataLink::ActiveChanged

TGridDataLink	See also

Informs the TCustomDBGrid of changes in the Active property.

virtual void __fastcall ActiveChanged(void);

Description

Applications can not call the ActiveChanged procedure directly. Changes in the Active property trigger this procedure. When the dataset becomes inactive, ActiveChanged makes sure that the grid is not in edit mode. When the dataset becomes active, ActiveChanged makes sure that the grid does not contain references to fields that are no longer in the dataset, and that the grid does is not scrolled inappropriately.


TGridDataLink::AddMapping

TGridDataLink	See also

Adds a field component to the end of the field map.

bool __fastcall AddMapping(const System::AnsiString FieldName);

Description

Applications should not call AddMapping directly, because this would cause the field map to become out of sync with the columns in TCustomDBGrid. TCustomDBGrid calls AddMapping iteratively to build a field map that corresponds to its columns.


TGridDataLink::ClearMapping

TGridDataLink	See also

Empties the field map and frees any associated memory.

void __fastcall ClearMapping(void);

Description

Applications should not call ClearMapping directly, because this would cause the field map to become out of sync with the columns of the TCustomDBGrid. The TCustomDBGrid calls ClearMapping first, every time it regenerates the field map.


TGridDataLink::TGridDataLink

TGridDataLink	See also

Creates an instance of TGridDataLink.

__fastcall TGridDataLink(TCustomDBGrid* AGrid);

Description

Applications should not directly instantiate a TGridDataLink object. The TCustomDBGrid object that owns a TGridDataLink creates the TGridDataLink from its own constructor.


TGridDataLink::DataSetChanged

TGridDataLink	See also

Informs TCustomDBGrid of changes to the dataset.

virtual void __fastcall DataSetChanged(void);

Description

Applications can not call DataSetChanged directly. Changes to the contents of the dataset trigger this method automatically. DataSetChanged allows the TCustomDBGrid to keep track of when the contents of the dataset change.


TGridDataLink::DataSetScrolled

TGridDataLink	See also

Informs the TCustomDBGrid when the dataset has finished scrolling.

virtual void __fastcall DataSetScrolled(int Distance);

Description

Applications can not call the DataSetScrolled procedure directly. This procedure is called automatically after the dataset for the TCustomDBGrid scrolls. TGridDataLink informs the TCustomDBGrid that a scroll of the dataset has just occurred by calling its Scroll method.


TGridDataLink::~TGridDataLink

TGridDataLink	See also

Destroys an instance of TGridDataLink.

__fastcall virtual ~TGridDataLink(void);

Description

Do not destroy a TGridDataLink in an application. The TCustomDBGrid that owns a TGridDataLink destroys it from its own destructor.

~TGridDataLink frees up the memory used by the field map before calling the parent class’s destructor.


TGridDataLink::EditingChanged

TGridDataLink	See also

Informs the TCustomDBGrid of changes in the editing state of the dataset.

virtual void __fastcall EditingChanged(void);

Description

Applications can not call the EditingChanged procedure directly. Changes in the Editing property trigger this procedure. EditingChanged allows the TCustomDBGrid to provide visual feedback to the user about the editing state of the dataset.


TGridDataLink::FocusControl

TGridDataLink	See also

Displays the editor and gives focus to a field control in the TCustomDBGrid object.

virtual void __fastcall FocusControl(Db::TFieldRef Field);

Description

Call the FocusControl procedure to bring up the editor for the representation of Field in the TCustomDBGrid. FocusControl selects Field in the TCustomDBGrid, and then tells the TCustomDBGrid object to bring up the editor.


TGridDataLink::GetMappedIndex

TGridDataLink	See also

GetMappedIndex provides the index of a field component in the dataset that corresponds to an index within the field map.

int __fastcall GetMappedIndex(int ColIndex);

Description

Use GetMappedIndex on an index into the field map to get an index into the dataset for the same field component. Both the field map and the dataset are zero-based arrays. If an entry in the field map is an undefined field, GetMappedIndex returns -1.


TGridDataLink::LayoutChanged

TGridDataLink	See also

Informs the grid after the layout of the TCustomDBGrid has changed in a way that affects the representation of the dataset.

virtual void __fastcall LayoutChanged(void);

Description

Applications can not call the LayoutChanged method directly. The TCustomDBGrid that owns the TGridDataLink calls this method automatically when layout changes affect the representation of the dataset. LayoutChanged allows the TCustomDBGrid to regenerate its layout by calling its LayoutChanged method.


TGridDataLink::Modified

TGridDataLink	See also

Tracks changes to the data which have not been written to the current record in the database.

void __fastcall Modified(void);

Description

Applications should not call Modified directly. Modified is called automatically whenever the TCustomDBGrid starts editing one of its fields. Modified allows the TGridDataLink to keep track of whether there are any edits that have not been posted.


TGridDataLink::RecordChanged

TGridDataLink	See also

Informs the grid of changes in the current record or field of the DataSource.

virtual void __fastcall RecordChanged(Db::TField* Field);

Description

Applications can not call RecordChanged directly. It is called automatically when the contents of the current record change. The Field parameter indicates which field in the current record has changed. If Field is NULL, the entire record has changed.

RecordChanged informs TCustomDBGrid of these changes so that it can update the display of the affected column or columns.


TGridDataLink::Reset

TGridDataLink	See also

Cancels any pending edits to the dataset that have not been written to the current record in the database.

void __fastcall Reset(void);

Description

Reset is triggered by user actions that cancel any pending edits to the dataset.


TGridDataLink::UpdateData

TGridDataLink	See also

Allows the grid to post changes to the dataset.

virtual void __fastcall UpdateData(void);

Description

Applications can not call the UpdateData procedure directly. It is called automatically when pending changes need to be posted to the dataset. UpdateData tells the TCustomDBGrid to write any unposted changes to the current field to the underlying Field component.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


 TGroupBox

Hierarchy	Properties	Methods	Events	See also

TGroupBox represents a Windows group box.

Unit

stdctrls

Description

The TGroupBox component represents a standard Windows group box, used to group related controls on a form. When another control component is placed within a group box, the group box becomes the parent of that component.


TGroupBox properties

TGroupBox	Alphabetically	Legend

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TGroupBox properties

TGroupBox	By object	Legend

Align

BoundsRect

Brush

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TGroupBox events

TGroupBox	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TGroupBox events

TGroupBox	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TGroupBox methods

TGroupBox	Alphabetically

In TGroupBox

~TGroupBox

TGroupBox

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TGroupBox methods

TGroupBox	By object

~TGroupBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TGroupBox

Update

UpdateControlState


TGroupBox::TGroupBox

TGroupBox

TGroupBox creates a new TGroupBox object.

__fastcall virtual TGroupBox(Classes::TComponent* AOwner) : Stdctrls::TCustomGroupBox(AOwner) { }

__fastcall TGroupBox(HWND ParentWindow) : Stdctrls::TCustomGroupBox(ParentWindow) { }

Description

Do not call TGroupBox directly. Instead, use the keyword new, which returns an indirect reference to the new group box. TGroupBox objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the group box with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the group box in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the group box is implemented as an ActiveX control.


TGroupBox::~TGroupBox

TGroupBox

~TGroupBox frees the memory associated with the TGroupBox object.

__fastcall virtual ~TGroupBox(void) { }

Description

Do not call ~TGroupBox directly. Instead, use the delete keyword on the object, which causes ~TGroupBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGroupBox


TGraphicControl

Hierarchy	Properties	Methods	See also

TGraphicControl is the base class for all nonwindowed custom controls.

Unit

controls

Description

The primary purpose of most graphic controls is to display text or graphics. C++Builder controls that descend from TGraphicControl include TBevel, TImage, TPaintBox, TShape, TSpeedButton, TSplitter, and TCustomLabel, from which TDBText and TLabel are derived.

In addition to everything inherited from the abstract TControl component, TGraphicControl provides a Canvas property that provides ready access to the control's drawing surface and a virtual Paint method called in response to WM_PAINT messages received by a parent control.

Graphic controls cannot receive the input focus, nor can they contain other controls. Because a graphic control doesn’t need a Windows handle, it’s demand on system resources is lessened, and painting a graphic control is quicker than painting a windowed control.

To create a control that can receive input focus or contain other controls, but which needs a Canvas property and a Paint method, derive a class from TCustomControl.


TGraphicControl properties

TGraphicControl	Alphabetically	Legend

In TGraphicControl

Canvas

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TGraphicControl properties

TGraphicControl	By object	Legend

Align

BoundsRect

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Height

Hint

Left

Name

Owner

Parent

ShowHint

Tag

Top

VCLComObject

Visible

Width

WindowProc


TGraphicControl::Canvas

TGraphicControl	See also	Example

Provides the drawing surface used by the graphic control.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

Use the properties of the TCanvas object to draw or paint on the surface of the control. Canvas provides all the tools and methods needed for drawing and painting.

Since TGraphicControl does not have its own window, when Canvas needs a handle to a device context, it uses the device context obtained from the window of the control’s Parent.


TGraphicControl methods

TGraphicControl	Alphabetically	Legend

In TGraphicControl

~TGraphicControl

Paint

TGraphicControl

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TGraphicControl methods

TGraphicControl	By object	Legend

~TGraphicControl

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Paint

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TGraphicControl

Update


TGraphicControl::TGraphicControl

TGraphicControl	See also

Creates an instance of TGraphicControl.

__fastcall virtual TGraphicControl(Classes::TComponent* AOwner);

Description

Do not call TGraphicControl directly. Instead, use the new keyword to instantiate and initialize a graphic control descendant at runtime. Graphic controls placed on forms at design time are created automatically.

TGraphicControl creates the TCanvas object for the Canvas property after calling the parent class’s constructor.


TGraphicControl::~TGraphicControl

TGraphicControl	See also

Destroys an instance of TGraphicControl.

__fastcall virtual ~TGraphicControl(void);

Description

Do not call ~TGraphicControl directly in an application. Instead, use the delete keyword.


TGraphicControl::Paint

TGraphicControl	See also

Provides the interface for a method that renders the image of the graphic control.

virtual void __fastcall Paint(void);

Description

A graphic control receives WM_PAINT messages from its Parent, when the parent wants the graphic control to paint itself. Graphic controls respond to WM_PAINT messages by initializing the control's canvas and calling the Paint method. Override Paint to specify how the image of the control should be drawn.

The Paint method for TGraphicControl does nothing more than provide an interface to be overridden by derived objects. All graphic controls that can be instantiated must override Paint to draw the image of the control.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl


THandleObject

Hierarchy	Properties	Methods	See also

THandleObject is the base class for all thread synchronization objects that use a handle.

Unit

syncobjs

Description

Use THandleObject as a base class when defining an object that uses a handle when coordinating the execution of different threads in a multi-threaded application. Handled synchronization objects include event objects that allow threads to signal when critical events have occurred.

Do not create instances of THandleObject. THandleObject is a base class that introduces properties for managing the handle of a synchronization object but does not provide a mechanism for acquiring that handle. Descendants of THandleObject must acquire the appropriate type of handle.


THandleObject properties

THandleObject	Alphabetically	Legend

In THandleObject

Handle

LastError


THandleObject properties

THandleObject	By object	Legend

Handle

LastError


THandleObject::Handle

THandleObject	See also

Specifies the handle of the Windows object used by THandleObject.

__property int Handle = {read=FHandle, nodefault};

Description

Read Handle to obtain the Windows handle for the synchronization object. Use Handle when making Windows API calls that require a handle to the synchronization object.

THandleObject provides no mechanism for setting the Handle property. Descendants of THandleObject set the Handle property to the handle for whatever Windows synchronization object they represent.


THandleObject::LastError

THandleObject	See also

Indicates the Windows error code obtained from Handle.

__property int LastError = {read=FLastError, nodefault};

Description

Read LastError when an operation of the THandleObject fails. LastError returns the Windows error code that represents the reason for the failure. If no operation failed, LastError is 0.


THandleObject methods

THandleObject	Alphabetically

In THandleObject

~THandleObject

THandleObject

Derived from TSynchroObject

Acquire

Release

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THandleObject methods

THandleObject	By object

~THandleObject

Acquire

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Release

SafeCallException

THandleObject


THandleObject::~THandleObject

THandleObject	See also

Destroys an instance of THandleObject.

__fastcall virtual ~THandleObject(void);

Description

Do not call ~THandleObject directly in an application. Instead, use the delete keyword.

~THandleObject releases the handle before calling the parent class’s destructor.


THandleObject::THandleObject

THandleObject

Creates a new THandleObject object.

__fastcall THandleObject(void) : Syncobjs::TSynchroObject() { }

Description

Do not create instances of THandleObject. THandleObject is a base class that provides no mechanism for setting the handle. Instead, use the constructor for a THandleObject descendant.


Accessibility

Read-only


Hierarchy

TObject

TSynchroObject


 THeaderControl

Hierarchy	Properties	Methods	Events	See also

THeaderControl is a container for THeaderSection objects. It provides a set of resizable column headers.

Unit

comctrls

Description

A THeaderControl is a set of column headers that the user can resize at runtime. Each header is represented by a THeaderSection object listed in the Sections property.

The header sections can be positioned above columns or fields of information. For example, header sections could be placed over a list box (TListBox). Because THeaderControl provides a generic header element that can be paired with virtually any other visual component, runtime manipulation of the header sections is not automatically extended to the components beneath it. If, for example, you want the column beneath a header section to be resized whenever the header section is resized, you will have to write a custom OnSectionResize event handler to accomplish this.


THeaderControl properties

THeaderControl	Alphabetically	Legend

In THeaderControl

Canvas

HotTrack

Sections

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


THeaderControl properties

THeaderControl	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

HotTrack

Left

Name

Owner

Parent

ParentFont

ParentShowHint

ParentWindow

PopupMenu

Sections

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


THeaderControl::Canvas

THeaderControl	See also 	Example

Provides runtime access to the header control’s drawing surface.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

The read-only Canvas property provides access to the header control’s drawing surface that can be used when implementing a handler for the OnDrawSection event.


THeaderControl::HotTrack

THeaderControl	See also

Highlights the header sections as the mouse passes over them.

__property bool HotTrack = {read=FHotTrack, write=SetHotTrack, default=0};

Description

If HotTrack is set to true, the text on each header section appears highlighted when the mouse passes over it at runtime.


THeaderControl::Sections

THeaderControl	See also	Example

Lists the header sections (column headings).

__property THeaderSections* Sections = {read=FSections, write=SetSections};

Description

The Sections property holds a THeaderSections—that is, a collection of THeaderSection objects. At design time, header sections can be added, removed, or modified with the Sections editor. To open the Sections editor, select the Sections property in the Object Inspector, then double-click in the Value column to the right or click the ellipsis (...) button.


THeaderControl events

THeaderControl	Alphabetically	Legend

In THeaderControl

OnDrawSection

OnResize

OnSectionClick

OnSectionResize

OnSectionTrack

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


THeaderControl events

THeaderControl	By object	Legend

OnDragDrop

OnDragOver

OnDrawSection

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnSectionClick

OnSectionResize

OnSectionTrack

OnStartDrag


THeaderControl::OnDrawSection

THeaderControl	See also	Example

Occurs when a header section needs to be redrawn.

typedef void __fastcall (__closure *TDrawSectionEvent)(THeaderControl* HeaderControl, THeaderSection* Section, const Windows::TRect &Rect, bool Pressed);

__property TDrawSectionEvent OnDrawSection = {read=FOnDrawSection, write=FOnDrawSection};

Description

The OnDrawSection event occurs when a header section needs to be redisplayed—for example, when the user selects or resizes a section. OnDrawSection occurs only if the header section’s Style property is set to hsOwnerDraw.

TDrawSectionEvent is the type of the OnDrawSection property.


THeaderControl::OnResize

THeaderControl	See also

Occurs when the header control is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

The OnResize event occurs when the size of the header control changes at runtime.


THeaderControl::OnSectionClick

THeaderControl	See also

Occurs when one of the header control’s sections is clicked.

typedef void __fastcall (__closure *TSectionNotifyEvent)(THeaderControl* HeaderControl, THeaderSection* Section);

__property TSectionNotifyEvent OnSectionClick = {read=FOnSectionClick, write=FOnSectionClick};

Description

The OnSectionClick event occurs when a header section is clicked at runtime. To disable a section from being clicked set its AllowClick property to false.

TSectionNotifyEvent is the type of the OnSectionClick and OnSectionResize events.


THeaderControl::OnSectionResize

THeaderControl	See also

Occurs when one of the header control’s sections is resized.

typedef void __fastcall (__closure *TSectionNotifyEvent)(THeaderControl* HeaderControl, THeaderSection* Section);

__property TSectionNotifyEvent OnSectionResize = {read=FOnSectionResize, write=FOnSectionResize};

Description

The OnSectionResize event occurs when a header section is resized at runtime. This happens when the user positions the mouse pointer between two sections and drags their border to the right or left.

TSectionNotifyEvent is the type of the OnSectionClick and OnSectionResize events.


THeaderControl::OnSectionTrack

THeaderControl	See also

Occurs as one of the header control’s sections is being resized.

enum TSectionTrackState { tsTrackBegin, tsTrackMove, tsTrackEnd };

typedef void __fastcall (__closure *TSectionTrackEvent)(THeaderControl* HeaderControl, THeaderSection* Section, int Width, TSectionTrackState State);

__property TSectionTrackEvent OnSectionTrack = {read=FOnSectionTrack, write=FOnSectionTrack};

Description

The OnSectionTrack event tracks the dragging of a header section’s border as it happens. OnSectionTrack occurs when the mouse pointer is positioned between two header sections and the left mouse button is depressed.

OnSectionTrack is of type TSectionTrackEvent, whose Width and State parameters indicate the size of the header section (in pixels) and the status of the event. The State property can take three values:

Value	Meaning

tsTrackBegin	The border has not yet been dragged.

tsTrackMove	The border is being dragged.

tsTrackEnd	The border is no longer being dragged.

Use OnSectionTrack when you want something to happen at runtime as a header section is being resized.


THeaderControl methods

THeaderControl	Alphabetically

In THeaderControl

~THeaderControl

THeaderControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


THeaderControl methods

THeaderControl	By object

~THeaderControl

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

THeaderControl

Update

UpdateControlState


THeaderControl::THeaderControl

THeaderControl	See also

Creates and initializes a THeaderControl component.

__fastcall virtual THeaderControl(Classes::TComponent* AOwner);

__fastcall THeaderControl(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not call THeaderControl directly. Instead, use the keyword new, which returns an indirect reference to the new header control. THeaderControl objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the header control with an owner that is responsible for freeing it. This is the most commonly used constructor syntax.

To embed the header control in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the header control is implemented in an ActiveX control.

The THeaderControl method creates a header control along with its canvas and header sections.


THeaderControl::~THeaderControl

THeaderControl	See also

Destroys THeaderControl and frees its memory.

__fastcall virtual ~THeaderControl(void);

Description

Do not call ~THeaderControl directly. Instead, use the delete keyword on the object, which causes ~THeaderControl to be invoked automatically.

The ~THeaderControl method destroys the header control along with its canvas and header sections.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


THeaderSection

Hierarchy	Properties	Methods	See also

THeaderSection represents a section of a header control.

Unit

comctrls

Description

Each THeaderControl uses a THeaderSections to maintain a collection of THeaderSection objects.


THeaderSection properties

THeaderSection	Alphabetically	Legend

In THeaderSection

Alignment

AllowClick

DisplayName

Left

MaxWidth

MinWidth

Right

Style

Text

Width

Derived from TCollectionItem

Collection

ID

Index


THeaderSection properties

THeaderSection	By object	Legend

Alignment

AllowClick

Collection

DisplayName

ID

Index

Left

MaxWidth

MinWidth

Right

Style

Text

Width


THeaderSection::Alignment

THeaderSection	See also

Specifies how text is aligned within the header section.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

These are the possible values of Alignment:

Value	Meaning

taLeftJustify	Align text on the left side of the header section.

taCenter	Center text in the header section.

taRightJustify	Align text on the right side of the header section.


THeaderSection::AllowClick

THeaderSection	See also

Allows the section to respond to mouse clicks at runtime.

__property bool AllowClick = {read=FAllowClick, write=FAllowClick, default=1};

Description

If AllowClick is set to true (the default), the header section can be clicked with the mouse at runtime. Header sections behave like buttons when clicked: They loose their raised borders and appear depressed on the form. To attach functionality to the clicking of header sections, write an event handler for the header control’s OnSectionClick event.


THeaderSection::DisplayName

THeaderSection	See also

The name displayed in the Sections editor.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

DisplayName is the string that represents the item in the Sections property editor.


THeaderSection::Left

THeaderSection	See also

Specifies the horizontal position of the header section’s left edge.

__property int Left = {read=GetLeft, nodefault};

Description

The Left property is the horizontal coordinate of the header section’s left edge, relative to the left border of the the header control and measured in pixels.


THeaderSection::MaxWidth

THeaderSection	See also

Specifies the maximum width of the header section.

__property int MaxWidth = {read=FMaxWidth, write=SetMaxWidth, default=10000};

Description

Sets the maximum width, in pixels, for the header section. If MaxWidth = MinWidth, the header section cannot be resized at runtime.


THeaderSection::MinWidth

THeaderSection	See also 	Example

Specifies the minimum width of the header section.

__property int MinWidth = {read=FMinWidth, write=SetMinWidth, default=0};

Description

Sets the minimum width, in pixels, for the header section. If MinWidth = MaxWidth, the header section cannot be resized at runtime.


THeaderSection::Right

THeaderSection	See also

Specifies the horizontal position of the header section’s right edge.

__property int Right = {read=GetRight, nodefault};

Description

The Right property is the horizontal coordinate of the header section’s right edge, relative to the left border of the the header control and measured in pixels. The Right value is the value of Left plus the value of Width.


THeaderSection::Style

THeaderSection	See also 	Example

Determines how the header section’s text is displayed.

enum THeaderSectionStyle { hsText, hsOwnerDraw };

__property THeaderSectionStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

If Style is set to hsText (the default), the string contained in the Text property is displayed in the header section, using the alignment specified by Alignment. The font is determined by the header control’s Font property.

If Style is set to hsOwnerDraw, the content displayed in the header section is drawn at run time on the header control’s canvas by code in a THeaderControl::OnDrawSection event handler.


THeaderSection::Text

THeaderSection	See also

Specifies the header section’s caption.

__property System::AnsiString Text = {read=FText, write=SetText};

Description

The Text property contains a string that identifies the header section or the column beneath it. If Style is set to hsText, the value of Text appears in the header section.


THeaderSection::Width

THeaderSection	See also

Specifies the width of the header section.

__property int Width = {read=FWidth, write=SetWidth, nodefault};

Description

The Width property determines the default width of the header section, in pixels. Header sections can be resized at runtime by dragging their borders.


THeaderSection methods

THeaderSection	Alphabetically

In THeaderSection

~THeaderSection

Assign

THeaderSection

Derived from TCollectionItem

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THeaderSection methods

THeaderSection	By object

~THeaderSection

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

THeaderSection


THeaderSection::Assign

THeaderSection	See also

Copies the contents of the source header section to a new header section.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the values of the source object’s Alignment, AllowClick, MaxWidth, MinWidth, Style, Text, and Width properties to another header section.


THeaderSection::THeaderSection

THeaderSection	See also

Creates and initializes a header section.

__fastcall virtual THeaderSection(Classes::TCollection* Collection);

Description

Do not call THeaderSection directly. Instead, use the keyword new, which returns an indirect reference to the new header section. THeaderSection objects placed on a form at design time are created automatically.

THeaderSection takes a THeaderSections instance as its argument.


THeaderSection::~THeaderSection

THeaderSection

~THeaderSection frees the memory associated with the THeaderSection object.

__fastcall virtual ~THeaderSection(void) { }

Description

Do not call ~THeaderSection directly. Instead, use the delete keyword on the object, which causes ~THeaderSection to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


THeaderSections

Hierarchy	Properties	Methods	See also

THeaderSections is a container for THeaderSection objects.

Unit

comctrls

Description

Each THeaderSections holds a collection of THeaderSection objects in a THeaderControl. THeaderSections maintains an index of the header sections in its Items array. The Count property contains the number of header sections in the collection. At design time, use the header control’s Sections editor to add, remove, or modify header sections.


THeaderSections properties

THeaderSections	Alphabetically	Legend

In THeaderSections

Items

Derived from TCollection

Count

ItemClass


THeaderSections properties

THeaderSections	By object	Legend

Count

ItemClass

Items


THeaderSections::Items

THeaderSections	See also

Lists the header sections in the collection.

__property THeaderSection* Items[int Index] = {read=GetItem, write=SetItem};

Description

The value of the Index parameter corresponds to the Index property of THeaderSection. It represents the position of the header section in the header.


THeaderSections methods

THeaderSections	Alphabetically

In THeaderSections

~THeaderSections

Add

THeaderSections

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THeaderSections methods

THeaderSections	By object

~THeaderSections

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

THeaderSections


THeaderSections.Add

THeaderSections	See also 	Example

Creates a new THeaderSection instance and adds it to the Items array.

HIDESBASE THeaderSection* __fastcall Add(void);

Description

Add returns the new header section. At design time, use the header control’s Sections editor to add sections to the header.


THeaderSections::THeaderSections

THeaderSections	See also

Creates and initializes a THeaderSections object.

__fastcall THeaderSections(THeaderControl* HeaderControl);

Description

Do not call THeaderSections directly. Instead, use the keyword new, which returns an indirect reference to the new object. THeaderSections objects placed on a form at design time are created automatically.

The THeaderSections method takes a THeaderControl instance as a parameter.


THeaderSections::~THeaderSections

THeaderSections

~THeaderSections frees the memory associated with the THeaderSections object.

__fastcall virtual ~THeaderSections(void) { }

Description

Do not call ~THeaderSections directly. Instead, use the delete keyword on the object, which causes ~THeaderSections to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


THintWindow

Hierarchy	Properties	Methods	See also

THintWindow implements the small pop-up window that appears over a control at runtime when the control has its ShowHint property set to true.

Unit

controls

Description

Use THintWindow to display a Help Hint pop-up window directly from an application. Override THintWindow to customize the window that appears automatically for controls with their ShowHint property set to true. After overriding THintWindow to create a new derived type, assign the new type to the global HintWindowClass variable at application startup, so that the new hint window type is used for Help Hints.


THintWindow properties

THintWindow	Alphabetically	Legend

Derived from TCustomControl

Canvas

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


THintWindow properties

THintWindow	By object	Legend

Align

BoundsRect

Brush

Canvas

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


THintWindow methods

THintWindow	Alphabetically

In THintWindow

~THintWindow

ActivateHint

ActivateHintData

CalcHintRect

IsHintMsg

ReleaseHandle

THintWindow

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


THintWindow methods

THintWindow	By object

~THintWindow

ActivateHint

ActivateHintData

Assign

BeginDrag

BringToFront

Broadcast

CalcHintRect

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

IsHintMsg

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

ReleaseHandle

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

THintWindow

Update

UpdateControlState


THintWindow::ActivateHint

THintWindow	See also

Displays the hint window.

virtual void __fastcall ActivateHint(const Windows::TRect &Rect, const System::AnsiString AHint);

Description

Call ActivateHint to display the hint window at the coordinates provided by the Rect parameter. If the Rect parameter appears off screen, ActivateHint moves the hint window to the closest approximation to the coordinates supplied by Rect that appears entirely on screen. ActivateHint sets the Caption property to the AHint parameter before showing the window, so that the AHint string appears to the user.

After an application displays a hint window, it automatically deactivates it after a time period has elapsed, or when it receives a message that requires hiding the hint message. To hide the hint window that is brought up automatically by the application, use the HideHint method of the global Application object. To hide a hint window that is activated directly by calling ActivateHint, use the ReleaseHandle method.


THintWindow::ActivateHintData

THintWindow	See also

Displays the hint window using a provided data value.

virtual void __fastcall ActivateHintData(const Windows::TRect &Rect, const System::AnsiString AHint, void * AData);

Description

Call ActivateHintData to display the hint window at the coordinates provided by the Rect parameter. The ActivateHintData method for THintWindow sets the Caption property to the AHint parameter and ignores the AData parameter. Descendant classes can override this method to combine the AHint and AData parameters into a customized Hint value.

After an application displays a hint window, it automatically deactivates it after a time period has elapsed, or when it receives a message that requires hiding the hint message. To hide the hint window that is brought up automatically by the application, use the HideHint method of the global Application object. To hide a hint window that is activated directly by calling ActivateHint, use the ReleaseHandle method.


THintWindow::CalcHintRect

THintWindow	See also

Returns the size needed to display a given hint.

virtual Windows::TRect __fastcall CalcHintRect(int MaxWidth, const System::AnsiString AHint, void * AData);

Description

Call CalcHintRect to determine the size needed to display a hint window for the string and data supplied by the AHint and AData parameters. The MaxWidth parameter limits how wide the Hint window can grow before the text wraps to a new line.


THintWindow::THintWindow

THintWindow	See also

Creates and initializes an instance of THintWindow.

__fastcall virtual THintWindow(Classes::TComponent* AOwner);

__fastcall THintWindow(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Do not call THintWindow directly when creating a hint window control at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created THintWindow object.

Hint windows activated by the application in response to the ShowHint property of a control are created automatically.

Pass a single Component as a parameter to provide the THintWindow object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the hint window control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


THintWindow::IsHintMsg

THintWindow	See also

Determines whether an application message requires hiding the hint window.

virtual bool __fastcall IsHintMsg(tagMSG &Msg);

Description

Call IsHintMsg to determine whether the message specified by the Msg parameter requires hiding the hint window. Upon seeing a mouse, keyboard, command, or activation message, IsHintMsg returns true. The global Application object calls IsHintMsg to check messages while the hint window is on the screen, and hides the window if IsHintMsg returns true.


THintWindow::ReleaseHandle

THintWindow	See also

Destroys the window displayed by THintWindow.

void __fastcall ReleaseHandle(void);

Description

Call ReleaseHandle to destroy a hint window that was activated by directly calling the ActivateHint method. Hint windows activated automatically by the application object are deactivated by the application as well.


THintWindow::~THintWindow

THintWindow

~THintWindow frees the memory associated with the THintWindow object.

__fastcall virtual ~THintWindow(void) { }

Description

Do not call ~THintWindow directly. Instead, use the delete keyword on the object, which causes ~THintWindow to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


THandleStream

Hierarchy	Properties	Methods	See also

THandleStream is a stream object that enables applications to read from and write to communications resources identified by a Windows handle.

Unit

classes

Description

Use THandleStream to access files, sockets, named pipes, mailslots, or other communications resources that provide a Windows handle when opened. For example, the FileOpen function provides a Windows handle for a file on disk. THandleStream allows applications to use a uniform stream interface when performing I/O using a Windows handle.

To avoid the overhead of managing file handles, use TFileStream to work with disk files.


THandleStream properties

THandleStream	Alphabetically	Legend

In THandleStream

Handle

Size

Derived from TStream

Position


THandleStream properties

THandleStream	By object	Legend

Handle

Position

Size


THandleStream::Handle

THandleStream	See also

Specifies the handle for the communications resource the stream reads from and writes to.

__property int Handle = {read=FHandle, nodefault};

Description

Read Handle to get the handle for Windows API calls or file management functions. To read from or write to the resource, use the methods of the THandleStream object.

Handle is a read-only property. The handle property cannot be changed to allow the handle stream to switch from reading to writing or vice versa. For example, to change from a file handle that is opened in read-only mode to one that is opened in write mode:

1	Free the stream object.

2	Call FileClose to close the file.

3	Re-open the file in write mode, and use the handle to create a new instance of a handle stream. Alternately, open a TFileStream object for the file, specifying a write mode for the stream.

Note:	Do not call the FileClose function on the Handle until after the THandleStream object has been destroyed.


THandleStream::Size

THandleStream	See also

Specifies the length, in bytes, of the resource identified by the Handle property.

__property int Size = {read=GetSize, write=SetSize, nodefault};

Description

Read Size to determine the number of bytes in the resource. Set Size to truncate the information in the resource. Not every communications resource that can be accessed using a THandleStream object can support the Size property. For example, do not use the Size property with named pipes.


THandleStream methods

THandleStream	Alphabetically	Legend

In THandleStream

~THandleStream

Read

Seek

SetSize

THandleStream

Write

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THandleStream methods

THandleStream	By object	Legend

~THandleStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

Seek

SetSize

THandleStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


THandleStream::THandleStream

THandleStream	See also

Creates an instance of THandleStream.

__fastcall THandleStream(int AHandle);

Description

Do not call THandleStream directly to instantiate a THandleStream object. Instead, use the new keyword, passing the resource handle as a parameter.

The handle must be obtained by opening or creating the resource in the appropriate mode. For example, to create a handle stream for reading from a file, obtain the file handle by opening the file with an fmOpenRead or fmOpenReadWrite mode. To create a handle stream for writing to a file, obtain the file handle by opening the file with an fmOpenWrite or fmOpenReadWrite mode.


THandleStream::Read

THandleStream	See also

Reads up to Count bytes of data from the resource associated with the handle stream into Buffer.

virtual int __fastcall Read(void *Buffer, int Count);

Description

Use Read to read data from the resource associated with the handle stream when the number of bytes in the file is not known. Read transfers up to Count bytes from the resource, starting at the current position, and then advances the current position in the resource by the number of bytes actually transferred. Read returns the number of bytes actually transferred, which may be less than Count if the end of file marker is encountered.

All other data-reading methods of a handle stream (ReadBuffer, ReadComponent) call Read to do the actual reading.


THandleStream::Seek

THandleStream	See also

Resets the current position of the handle stream.

virtual int __fastcall Seek(int Offset, Word Origin);

Description

Use Seek to move the current position within the resource associated with the handle stream by the indicated offset. Seek allows an application to read from or write to a particular location within the resource.

The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value	Meaning

soFromBeginning	Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.

soFromCurrent	Offset is from the current position in the resource. Seek moves to Position + Offset.

soFromEnd	Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Seek returns the new value of the Position property, the new current position in the resource.


THandleStream::SetSize

THandleStream	See also

Sets the end of file marker to truncate the resource at the indicated position.

virtual void __fastcall SetSize(int NewSize);

Description

Call SetSize to set the size of the resource. Size overrides the parent class’s method to allow the size of the resource identified by the handle to be changed. SetSize calls Seek to go to the indicated position, and then writes an end of file marker. If the size of the resource can not be changed, an exception is thrown. For example, calling SetSize for a file handle that was opened in fmOpenRead mode will throw an exception.


THandleStream::Write

THandleStream	See also

Writes Count bytes from the Buffer to the current position in the resource.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Use Write to write Count bytes to the resource associated with the handle stream, starting at the current position. After writing to the resource, Write advances the current position by the number bytes written, and returns the number of bytes written.

All other data-writing methods of a handle stream (WriteBuffer, WriteComponent) call Write to do the actual writing.


Accessibility

Read-only


THandleStream::~THandleStream

THandleStream

~THandleStream frees the memory associated with the THandleStream object.

__fastcall virtual ~THandleStream(void) { }

Description

Do not call ~THandleStream directly. Instead, use the delete keyword on the object, which causes ~THandleStream to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TStream


 THotKey

Hierarchy	Properties	Methods	Events

THotKey is a wrapper for a hot key Windows Common Control.

Unit

comctrls

Description

THotKey implements the generic behavior introduced in TCustomHotKey. THotKey publishes many of the properties parent class's from TCustomHotKey, but does not introduce any new behavior.

Use THotKey to create key combinations that can be used as a shortcut.


THotKey properties

THotKey	Alphabetically	Legend

Derived from TCustomHotKey

AutoSize

HotKey

InvalidKeys

Modifiers

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


THotKey properties

THotKey	By object	Legend

Align

AutoSize

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ControlCount

ControlState

Controls

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

HotKey

InvalidKeys

Left

Modifiers

Name

Owner

ParentShowHint

Parent

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


THotKey events

THotKey	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnMouseDown

OnMouseMove

OnMouseUp


THotKey events

THotKey	By object	Legend

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp


THotKey methods

THotKey	Alphabetically

In THotKey

~THotKey

THotKey

Derived from TCustomHotKey

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


THotKey methods

THotKey	By object

~THotKey

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

THotKey

Update

UpdateControlState


THotKey::THotKey

THotKey	See also

Creates a new THotKey object.

__fastcall virtual THotKey(Classes::TComponent* AOwner) : Comctrls::TCustomHotKey(AOwner) { }

__fastcall THotKey(HWND ParentWindow) : Comctrls::TCustomHotKey(ParentWindow) { }

Description

Call THotKey indirectly using the new keyword.

Pass a single Component as a parameter to provide the THotKey syntax. Pass a window handle as a parameter to embed THotKey in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


THotKey::~THotKey

THotKey

Frees the memory associated with the THotKey object.

__fastcall virtual ~THotKey(void) { }

Description

Do not call ~THotKey directly. Instead, use the delete keyword on the object, which causes ~THotKey to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomHotKey


TIconOptions

Hierarchy	Properties	Methods	See also

TIconOptions describes how the icons in a list view should be arranged.

Unit

comctrls

Description

Use TIconOptions with a list view object that has a ViewStyle of vsIcon or vsSmallIcon. Set the properties of the icon options object owned by the list view to represent how the icons in the list view should be arranged.

The properties of a TIconOptions object are not valid when it is not owned by a list view object.

Note:	TIconOptions has no effect if the associated list view does not have a ViewStyle of vsIcon or vsSmallIcon.


TIconOptions properties

TIconOptions	Alphabetically	Legend

In TIconOptions

Arrangement

AutoArrange

WrapText


TIconOptions properties

TIconOptions	By object	Legend

Arrangement

AutoArrange

WrapText


TIconOptions::Arrangement

TIconOptions	See also

Determines where the items are to be aligned in the list view.

enum TIconArrangement { iaTop, iaLeft };

__property TIconArrangement Arrangement = {read=FArrangement, write=SetArrangement, default=0};

Description

Set Arrangement to indicate whether the list view should display icon entries in rows or columns. Arrangement has no effect on the arrangement of entries in the list view when the ViewStyle is not vsIcon or vsSmallIcon. These are the possible values of Arrangement:

Value	Meaning

iaTop	Items are aligned left to right in rows at the top of the list view control

iaLeft	Items are aligned in columns top to bottom at the left of the list view control


TIconOptions::AutoArrange

TIconOptions	See also

Determines if icons in a list view are automatically rearranged when a list item is added, removed, or moved.

__property bool AutoArrange = {read=FAutoArrange, write=SetAutoArrange, default=0};

Description

Set AutoArrange to specify whether the list view object should rearrange its items whenever changes are made. If AutoArrange is true, the icons are automatically arranged. If AutoArrange is false, the icons are not arranged until the Arrange method of the list view is called.


TIconOptions::WrapText

TIconOptions	See also

Determines whether the caption of an icon in a list view is displayed all on one line, or if it can wrap.

__property bool WrapText = {read=FWrapText, write=SetWrapText, default=1};

Description

Set WrapText to true to have the caption of icons wrap rather than display on one line when it exceeds the width of the icon.


TIconOptions methods

TIconOptions	Alphabetically

In TIconOptions

~TIconOptions

TIconOptions

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TIconOptions methods

TIconOptions	By object

~TIconOptions

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TIconOptions


TIconOptions::TIconOptions

TIconOptions	See also

Creates an instance of TIconOptions.

__fastcall TIconOptions(TCustomListView* AOwner);

Description

Do not call TIconOptions directly in an application. The properties of TIconOptions are only valid when it is owned by a list view object. The list view instantiates a TIconOptions object to represent the arrangement properties of its icon views.

After calling the parent object’s constructor, TIconOptions initializes

•	Arrangement to iaTop.

•	AutoArrange to false.

•	WrapText to true.


TIconOptions::~TIconOptions

TIconOptions

Frees the memory associated with the TIconOptions object.

__fastcall virtual ~TIconOptions(void) { }

Description

Do not call ~TIconOptions. The properties of TIconOptions are only valid when the object is owned by a list view. List view’s handle the creation and destruction of their TIconOptions objects.


Scope

Published


Hierarchy

TObject

TPersistent


TIcon

Hierarchy	Properties	Methods	Events	See also

TIcon is an encapsulation of a Windows icon.

Unit

graphics

Description

Use TIcon to represent one of the icons in an image list. Assign an icon to objects that have an Icon property, such as TForm or TPicture.

Icon objects represent the value loaded from a Windows icon file (.ICO file). Draw an icon on a canvas, using the Draw method of the TCanvas object. Icons do not stretch, so do not use TCanvas::StretchDraw with an icon.


TIcon properties

TIcon	Alphabetically	Legend

In TIcon

Empty

Handle

Height

Width

Derived from TGraphic

Modified

Palette

PaletteModified

Transparent


TIcon properties

TIcon	By object	Legend

Empty

Handle

Height

Modified

Palette

PaletteModified

Transparent

Width


TIcon::Empty

Indicates whether the icon object contains an icon.

__property bool Empty = {read=GetEmpty, nodefault};

Description

If Empty is true, no icon has been loaded into the icon object. If Empty is false, the icon object contains an icon.


TIcon::Handle

TIcon	See also

Provides access to the Windows GDI icon handle.

__property HICON Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

Use Handle to specify the icon when using a Windows API function that requires the handle of an icon object. The Handle property is NULL if the icon has not been loaded.

Call the ReleaseHandle method before changing the icon image by setting the Handle property. The icon image can also be loaded by assigning another icon object or using the LoadFromClipboardFormat, LoadFromFile, or LoadFromStream method.


TIcon::Height

TIcon	See also

Specifies the vertical size of the icon in pixels.

__property int Height = {read=GetHeight, write=SetHeight, nodefault};

Description

All icons in an application have the same height, which is determined by Windows. Read Height to determine this common height.

Attempting to set the Height property throws an exception.


TIcon::Width

TIcon	See also

Specifies the horizontal size of the icon in pixels.

__property int Width = {read=GetWidth, write=SetWidth, nodefault};

Description

All icons in an application have the same width, which is determined by Windows. Read Width to determine this common width.

Attempting to set the Width property throws an exception.


TIcon events

TIcon	Alphabetically

Derived from TGraphic

OnChange

OnProgress


TIcon events

TIcon	By object

OnChange

OnProgress


TIcon methods

TIcon	Alphabetically

In TIcon

~TIcon

Assign

LoadFromStream

ReleaseHandle

SaveToStream

TIcon

Derived from TGraphic

LoadFromClipboardFormat

LoadFromFile

SaveToClipboardFormat

SaveToFile

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TIcon methods

TIcon	By object

~TIcon

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromClipboardFormat

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

ReleaseHandle

SafeCallException

SaveToClipboardFormat

SaveToFile

SaveToStream

TIcon


TIcon::Assign

TIcon	See also

Copies an icon image from another TIcon object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to copy another icon object. Assign copies the icon image from the Source parameter if it is another TIcon object. Otherwise, Assign calls the parent class's method, which copies the icon image from any source object that specifies how to copy to a TIcon in its AssignTo method.


TIcon::TIcon

TIcon	See also

Creates an instance of TIcon.

__fastcall virtual TIcon(void);

Description

Call TIcon to create an empty icon object. Once an image has been read into the icon from a file or stream, or by assigning another icon object, the icon can be drawn on a canvas or added to an image list. Do not create an icon object for setting the icon property of a form or picture. These objects create a TIcon object in their own constructors. Instead, use the LoadFromFile, LoadFromStream, or LoadFromClipboardFormat method on the TIcon object returned when reading the Icon property.


TIcon::~TIcon

TIcon	See also

Destroys an instance of TIcon.

__fastcall virtual ~TIcon(void);

Description

Do not call ~TIcon directly in an application. Instead, use the delete keyword on the object, which causes ~TIcon to be invoked automatically.

~TIcon releases the Windows icon handle before the object is freed.


TIcon::LoadFromStream

TIcon	See also

Loads the icon from a stream.

virtual void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Use LoadFromStream to read the icon image from a stream. Set the Stream parameter to a stream object that provides access to the memory image of the icon. To load the icon from a .ICO file, use the LoadFromFile method. To load the icon from the Clipboard, use the LoadFromClipboardFormat method.


TIcon::ReleaseHandle

TIcon	See also

Releases the Windows GDI object represented by the icon.

HICON __fastcall ReleaseHandle(void);

Description

Call ReleaseHandle to release the resources used to represent the icon. ReleaseHandle sets the Handle property to NULL.

ReleaseHandle informs the TIcon instance that it is no longer responsible for destroying the icon handle.


TIcon::SaveToStream

TIcon	See also

Saves the icon to a stream.

virtual void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Use SaveToStream to write the icon image to a stream. Specify the Stream parameter as the stream object that receives the memory image of the icon. To write the icon to a .ICO file, use the SaveToFile method. To write the icon to the Clipboard, use the SaveToClipboardFormat method.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TGraphic


TIconImage

Hierarchy	Methods	See also

TIconImage is the internal representation of the bitmap image for a TIcon object.

Unit

graphics

Description

TIconImage is used for internal implementation only in C++Builder. It represents the internal image of the bitmap encapsulated by the TIcon object. All of the data and methods introduced in TIconImage are private. They contain information about the specific HICON, including pointers to the standard HICON structures defined by Windows. TIconImage is referenced in the constructor of the TIcon object when the icon image is created.


TIconImage methods

TIconImage	Alphabetically

In TIconImage

~TIconImage

TIconImage

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TIconImage methods

TIconImage	By object

~TIconImage

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TIconImage


TIconImage::TIconImage

TIconImage

Creates a new TIconImage object.

__fastcall virtual ~TIconImage(void);

Description

Call TIconImage indirectly, using the new keyword, to create a bitmap image for a TIcon object at runtime.


TIconImage::~TIconImage

TIconImage

~TIconImage frees the memory associated with the TIconImage object.

__fastcall virtual ~TIconImage(void);

Description

Do not call ~TIconImage directly. Instead, use the delete keyword on the object, which causes ~TIconImage to be invoked automatically.


Hierarchy

TObject

TSharedImage


 TImage

Hierarchy	Properties	Methods	Events	See also

TImage displays a graphical image.

Unit

extctrls

Description

Use TImage to display a graphical image on a form. Use a TPicture object to specify the actual bitmap, icon, metafile, or other graphic object displayed by TImage. TImage introduces several properties to determine how the image is displayed within the boundaries of the TImage object.

To add an image to a form or data module so that it is available for display by other controls, use TImageList instead.


TImage properties

TImage	Alphabetically	Legend

In TImage

AutoSize

Canvas

Center

IncrementalDisplay

Picture

Stretch

Transparent

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TImage properties

TImage	By object	Legend

Align

AutoSize

BoundsRect

Canvas

Center

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Height

Hint

IncrementalDisplay

Left

Name

Owner

Parent

ParentShowHint

Picture

PopupMenu

ShowHint

Stretch

Tag

Top

Transparent

VCLComObject

Visible

Width

WindowProc


TImage::AutoSize

TImage	See also	Example

Determines whether the image control resizes to accommodate the image it displays.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=0};

Description

Set AutoSize to true to ensure that the entire image is visible within the image control. When AutoSize is true, the image control resizes to accommodate the image specified by the Picture property. When AutoSize is false, the image control remains the same size, regardless of the size of the image. If the image control is smaller than the image, only the portion of the picture that fits inside the image control is visible.

To resize the image to fit the image control rather than resizing the control to fit the image, use the Stretch property.


TImage::Canvas

TImage	See also 	Example

Provides a drawing surface for embellishing bitmap images.

__property Graphics::TCanvas* Canvas = {read=GetCanvas};

Description

Use Canvas to add to the image specified by the Picture property. For example, use the TextOut method of the TCanvas object to add labels to portions of the image.

Note:	Canvas is only available if the Picture property represents a bitmap. Trying to read Canvas when Picture is another type of graphic image throws an EInvalidOperation exception.


TImage::Center

TImage	See also

Indicates whether the image is centered in the image control.

__property bool Center = {read=FCenter, write=SetCenter, default=0};

Description

When the image does not fit perfectly within the image control, use Center to specify how the image is positioned. When Center is true, the image is centered in the control. When Center is false, the upper left corner of the image is positioned at the upper left corner of the control.

Note:	Center has no effect if the AutoSize property is true or if the Stretch property is true and Picture does not specify an icon.


TImage::IncrementalDisplay

TImage	See also

Specifies whether successive approximations of the image should be drawn during slow operations.

__property bool IncrementalDisplay = {read=FIncrementalDisplay, write=FIncrementalDisplay, default=0};

Description

Set IncrementalDisplay to true on large compressed images that take a long time to load or on images that may be altered by a computationally slow process. When IncrementalDisplay is true, partial renderings of the image are drawn periodically during slow operations such as loading. Set IncrementalDisplay to false to wait until the entire operation is complete before drawing the image.

For some classes of graphic objects, an OnProgress event occurs at various points during slow operations. If IncrementalDisplay is true, the OnProgress event occurs immediately after the approximate image is drawn. If IncrementalDisplay is false, OnProgress occurs, but the image is not updated.


TImage::Picture

TImage	See also 	Example

Specifies the image that appears on the image control.

__property Graphics::TPicture* Picture = {read=FPicture, write=SetPicture};

Description

Set Picture to a TPicture object that contains an icon, metafile, bitmap graphic, or user-defined graphic to be displayed by the image control. Setting Picture at design time brings up the Picture Editor, which can be used to specify the file that contains the image.


TImage::Stretch

TImage	See also

Indicates whether the image should be changed so that it exactly fits the bounds of the image control.

__property bool Stretch = {read=FStretch, write=SetStretch, default=0};

Description

Set Stretch to true to cause the image to assume the size and shape of the image control. When the image control resizes, the image resizes also. Stretch resizes the height and width of the image independently. Thus, unlike a simple change in magnification, stretch can distort the image if the image control is not the same shape as the image.

To resize the control to the image rather than resizing the image to the control, use the AutoSize property instead.

Note:	Stretch has no effect if the Picture property contains an icon.


TImage::Transparent

TImage	See also

Specifies whether the background of the image obscures objects below the image object.

__property bool Transparent = {read=FTransparent, write=SetTransparent, default=0};

Description

Set Transparent to true to allow objects behind the TImage object to show through the background of the bitmap.  Set Transparent to false to make the background of the bitmap opaque. Setting Transparent sets the Transparent property of the Picture.

Note:	Transparent has no effect unless the Picture property specifies a bitmap.


TImage events

TImage	Alphabetically	Legend

In TImage

OnProgress

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TImage events

TImage	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnProgress

OnStartDrag


TImage::OnProgress

TImage	See also

Occurs periodically during slow operations that affect the image.

__property Graphics::TProgressEvent OnProgress = {read=FOnProgress, write=FOnProgress};

Description

Write an OnProgress event handler to provide the user with feedback during slow operations such as loading large compressed images.

The Stage parameter indicates whether the operation is beginning, continuing, or ending. If the OnProgress event handler displays an indicator such as a progress bar, the indicator can be created when Stage is psStarting, updated while Stage is psRunning, and removed when Stage is psEnding. The PercentDone parameter is an approximation of how much of the operation has completed. Use PercentDone to update the position of a progress bar or other indicator.

The RedrawNow parameter indicates whether the image can safely be drawn on screen at this point. If the IncrementalDisplay property is true, an approximate image is drawn immediately before the OnProgress event when RedrawNow is true. The R parameter specifies the portion of the image that has changed and needs to be redrawn.

The Msg parameter contains one or two words that describe what operation is occurring. For example, the value of Msg could be a string such as Loading, Storing, or Reducing colors. The Msg string can also be empty.

Note:	The PercentDone parameter is only an approximation. With some image formats, the value of PercentDone may actually decrease from the value in previous events, as the graphic object discovers there is more work to do.


TImage methods

TImage	Alphabetically

In TImage

~TImage

TImage

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TImage methods

TImage	By object

~TImage

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TImage

Update


TImage::TImage

TImage	See also

Creates and initializes an instance of TImage.

__fastcall virtual TImage(Classes::TComponent* AOwner);

Description

Call TImage indirectly, using the new keyword, to instantiate a TImage object at runtime. Images placed on forms at design time are created automatically.


TImage::~TImage

TImage	See also

Destroys an instance of TImage.

__fastcall virtual ~TImage(void);

Description

Do not call ~TImage directly in an application. Instead, use the delete keyword.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


 TImageList

Hierarchy	Properties	Methods	Events	See also

The TImageList component is a collection of same-sized images, each of which can be referred to by its index.

Unit

controls

Description

Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style).

The image list is capable of holding a large number of same sized images and retrieving them via their index within the range 0 to n - 1. The image list also has methods to facilitate storing, retrieving, and drawing of the stored images.

The TImageList is derived from TCustomImageList and exposes many of the protected properties and methods of the TCustomImageList.


TImageList properties

TImageList	Alphabetically	Legend

Derived from TCustomImageList

AllocBy

BkColor

BlendColor

Count

DragCursor

Dragging

DrawingStyle

Handle

Height

ImageType

Masked

ShareImages

Width

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TImageList properties

TImageList	By object	Legend

AllocBy

BkColor

BlendColor

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

Count

DesignInfo

DragCursor

Dragging

DrawingStyle

Handle

Height

ImageType

Masked

Name

Owner

ShareImages

Tag

VCLComObject

Width


TImageList events

TImageList	Alphabetically	Legend

Derived from TCustomImageList

OnChange


TImageList events

TImageList	By object	Legend

OnChange


TImageList methods

TImageList	Alphabetically

In TImageList

~TImageList

TImageList

Derived from TCustomImageList

Add

AddIcon

AddImages

AddMasked

Assign

BeginDrag

Clear

CreateSize

Delete

DragLock

DragMove

DragUnlock

Draw

DrawOverlay

EndDrag

FileLoad

GetBitmap

GetHotSpot

GetIcon

GetImageBitmap

GetInstRes

GetMaskBitmap

GetResource

HandleAllocated

HideDragImage

Insert

InsertIcon

InsertMasked

Move

Overlay

RegisterChanges

Replace

ReplaceIcon

ReplaceMasked

ResInstLoad

ResourceLoad

SetDragImage

ShowDragImage

UnRegisterChanges

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TImageList methods

TImageList	By object

~TImageList

Add

AddIcon

AddImages

AddMasked

Assign

BeginDrag

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

CreateSize

DefaultHandler

Delete

DestroyComponents

Destroying

Dispatch

DragLock

DragMove

DragUnlock

Draw

DrawOverlay

EndDrag

FieldAddress

FileLoad

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetBitmap

GetHotSpot

GetIcon

GetImageBitmap

GetInstRes

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMaskBitmap

GetNamePath

GetParentComponent

GetResource

HandleAllocated

HasParent

HideDragImage

InheritsFrom

InitInstance

Insert

InsertComponent

InsertIcon

InsertMasked

InstanceSize

MethodAddress

MethodName

Move

NewInstance

Overlay

RegisterChanges

RemoveComponent

Replace

ReplaceIcon

ReplaceMasked

ResInstLoad

ResourceLoad

SafeCallException

SetDragImage

ShowDragImage

TImageList

UnRegisterChanges


TImageList::TImageList

TImageList

Creates a new TImageList object.

__fastcall virtual TImageList(Classes::TComponent* AOwner) : Controls::TCustomImageList(AOwner) { }

Description

Call TImageList indirectly, using the new keyword, to create a collection of same-sized images at runtime.


TImageList::~TImageList

TImageList

Frees the memory associated with the TImageList object.

__fastcall virtual ~TImageList(void) { }

Description

Do not call ~TImageList directly. Instead, use the delete keyword on the object, which causes ~TImageList to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomImageList


TIndexDef

Hierarchy	Properties	Methods	See also

TIndexDef describes an index in a database table.

Unit

db

Description

Use the properties and methods of an index definition to

•	Determine the name of an index.

•	Identify the fields that make up the index, or the dBASE expression that orders the index.

•	Determine the characteristics of the index.

Datasets that represent physical database tables use TIndexDef to create the indexes of the database table or to obtain information about the indexes when the table is not active.


TIndexDef properties

TIndexDef	Alphabetically	Legend

In TIndexDef

Expression

Fields

Options

Source

Derived from TNamedItem

DisplayName

Name

Derived from TCollectionItem

Collection

ID

Index


TIndexDef properties

TIndexDef	By object	Legend

Collection

DisplayName

Expression

Fields

ID

Index

Name

Options

Source


TIndexDef::Expression

TIndexDef	See also

Contains a dBASE key expression.

__property System::AnsiString Expression = {read=getExpression, write=SetExpression};

Description

Read Expression to learn the key expression of a dBASE expression index.

A key expression for a dBASE table is a field name or a combination of field names, functions, and operators that specifies how the index orders records in the table. If the table is not a dBASE table, Expression is an empty string.

If the Options property set does not contain the value ixExpression, the Expression property string returned is an empty string. To learn the fields in an index that is not a dBASE expression index, use the Fields property.

Note:	For more information about key expressions, see your dBASE documentation.


TIndexDef::Fields

TIndexDef	See also 	Example

Identifies the fields that compose the index.

__property System::AnsiString Fields = {read=GetFields, write=SetFields};

Description

Read Fields to determine the fields that make up the index. The string returned can be either the names of the fields, or the numbers of the field. When numbers are used, the numbers correspond to the physical field numbers in the table. Multiple fields in the string are separated by semicolons.

If the index is based on a dBASE key expression, the Fields property does not specify the fields that make up the index. Thus, if the Options property set contains the ixExpression value, Fields returns an empty string. To determine the specification of a dBASE expression index, use the Expression property instead.


TIndexDef::Options

TIndexDef	See also

Describes the characteristics of the index.

__property TIndexOptions Options = {read=FOptions, write=SetOptions, nodefault};

Description

Read Options to learn the attributes of the index. Options is a set, which can be empty, or can contain one or more of these values:

Value	Description

ixPrimary	The index is the primary index of the table.

ixUnique	Each value in the index is unique; there are no duplicates.

ixDescending	The index is in descending order.

ixExpression	The index order depends on a dBASE key expression.

ixCaseInsensitive	The index is case insensitive.

Note:	Different database drivers may support only a subset of these options. For example,  dBASE tables do not support ixCaseInsensitive.


TIndexDef::Source

TIndexDef	See also

Contains the name of a dBASE maintained index.

__property System::AnsiString Source = {read=FSource, write=SetSource};

Description

When the table uses dBASE .MDX indexes, Name indicates the index tag name and Source is the name of the index file. Source is applicable to dBASE table indexes only.


TIndexDef methods

TIndexDef	Alphabetically

In TIndexDef

~TIndexDef

Assign

TIndexDef

Derived from TCollectionItem

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TIndexDef methods

TIndexDef	By object

~TIndexDef

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TIndexDef


TIndexDef::Assign

TIndexDef	See also

Copies the properties of one index definition to another.

virtual void __fastcall Assign(Classes::TPersistent* ASource);

Description

Call Assign to copy an index definition. Assign checks whether the ASource parameter is another index definition, and, if so, copies the values of the Options, Name, Source, Expression, and Fields properties.

If the source is not an index definition, Assign calls the parent class's method, which assigns properties from any object that specifies how to copy to an index definition in its AssignTo method.


TIndexDef::TIndexDef

TIndexDef

Creates a new TIndexDef object.

__fastcall virtual TIndexDef(Classes::TCollection* Collection) : Db::TNamedItem(Collection) { }

Description

Call TIndexDef indirectly, using the new keyword, to create an index at runtime.


TIndexDef::~TIndexDef

TIndexDef

Frees the memory associated with the TIndexDef object.

__fastcall virtual ~TIndexDef(void) { }

Description

Do not call ~TIndexDef directly. Instead, use the delete keyword on the object, which causes ~TIndexDef to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem

TNamedItem


TIndexDefs

Hierarchy	Properties	Methods	See also

TIndexDefs holds the list of available index definitions for a table.

Unit

db

Description

Use the properties and methods of TIndexDefs to:

•	Access a specific index definition.

•	Determine how many index definitions this TIndexDefs object contains.

•	Add or delete index definitions.

•	Copy all index definitions from one TIndexDefs to another.

Datasets that represent physical database tables use TIndexDefs to create the indexes of the database table.


TIndexDefs properties

TIndexDefs	Alphabetically	Legend

In TIndexDefs

Items

Derived from TDefCollection

Dataset

Updated

Derived from TCollection

Count

ItemClass


TIndexDefs properties

TIndexDefs	By object	Legend

Count

Dataset

ItemClass

Items

Updated


TIndexDefs::Items
 KTIndexDefs::Items

TIndexDefs	See also 	Example

Lists the index definitions that describe each index of a table.

__property TIndexDef* Items[int Index] = {read=GetIndexDef, write=SetIndexDef};

Description

Use Items to access a particular index definition. Specify the index definition to access with the Index parameter. Index is an integer identifying the index definition’s position in the list of index definitions, in the range 0 to Count - 1.


TIndexDefs methods

TIndexDefs	Alphabetically

In TIndexDefs

~TIndexDefs

Add

AddIndexDef

Find

FindIndexForFields

GetIndexForFields

TIndexDefs

Update

Derived from TDefCollection

IndexOf

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TIndexDefs methods

TIndexDefs	By object

~TIndexDefs

Add

AddIndexDef

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

Find

FindIndexForFields

FindItemID

Free

FreeInstance

GetIndexForFields

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

IndexOf

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TIndexDefs

Update


TIndexDefs.Add
TIndexDefs::Add

TIndexDefs	See also 	Example

Creates a new index definition and adds it to the Items property.

HIDESBASE void __fastcall Add(const System::AnsiString N, const System::AnsiString F, TIndexOptions O);

Description

Add is provided for backward compatibility. The recommended way to add new field definitions before creating a table is to use the AddFieldDef method. To add an index to an existing table, use the AddIndex method of the TTable object instead. To change the array of indexes when a new index has been added to the dataset, use the Update method instead.

Add creates an index definition and assigns the values passed in the Name, Fields, and Options parameters to the TIndexDef properties of the same names.

If an index definition with same name already exists, an EDatabaseError exception is thrown.

The TIndexOptions type is the set of values that can be used in creating a new index. Options is a set, which can be empty, or can contain one or more of these values:

Value	Description

ixPrimary	The index is the primary index of the table.

ixUnique	Each value in the index is unique; there are no duplicates.

ixDescending	The index is in descending order.

ixExpression	The index order depends on a dBASE key expression.

ixCaseInsensitive	The index is case insensitive.

Note:	Different database drivers may support only a subset of these options. For example, with dBASE tables, ixCaseInsensitive is not supported.


TIndexDefs::AddIndexDef
TFieldDefs::AddIndexDef

TIndexDefs	See also

Creates a new index definition object and adds it to the Items property.

TIndexDef* __fastcall AddIndexDef(void);

Description

Call AddIndexDef to add index definitions when creating a database table. AddIndexDef returns the new index definition object that was added to the Items property array. Set the properties of the returned value to specify the type of index that should be created.


TIndexDefs::TIndexDefs

TIndexDefs	See also

Creates an instance of TIndexDefs.

__fastcall TIndexDefs(TDataSet* ADataset);

Description

Applications should not call TIndexDefs directly. TIndexDefs is created automatically by the dataset to specify the indexes for the table.


TIndexDefs::Find

TIndexDefs	See also

Locates an index definition in the Items array from the name of the index.

HIDESBASE TIndexDef* __fastcall Find(const System::AnsiString Name);

Description

Call Find to obtain information about a particular index definition. Specify the name of the index as the value of the Name parameter.

Find throws an EDatabaseError exception if there is no index definition with the given name.

Note:	To locate an index definition based on the indexed fields rather than the name of the index, use the FindIndexForFields method.


TIndexDefs::FindIndexForFields

TIndexDefs	See also

Locates an index definition in the Items array.

TIndexDef* __fastcall FindIndexForFields(const System::AnsiString Fields);

Description

Use FindIndexForFields to search for the index that starts with the fields specified in the Fields parameter. If the index comprises more than one field, separate the fields with semicolons.

FindIndexForFields returns the index definition that exactly matches the fields in the order specified, if one exists. If no exact match is found, FindIndexForFields returns the first index that begins with the indicated fields. If no match is found, FindIndexForFields throws an EDatabaseError exception.

Note:	To restrict the search to case insensitive indexes, use the GetIndexForFields method.


TIndexDefs::GetIndexForFields

TIndexDefs	See also

Locates an index definition in the Items array.

TIndexDef* __fastcall GetIndexForFields(const System::AnsiString Fields, bool CaseInsensitive);

Description

Use GetIndexForFields to search for the index that starts with the fields specified in the Fields parameter. If more than one field comprises the index, separate the fields with semicolons. Set the CaseInsensitive parameter to true to restrict the search to only the case insensitive indexes in the Items array.

GetIndexForFields returns the index definition that exactly matches the specified fields in the order specified, if it exists. If no exact match is found, GetIndexForFields returns the first index that begins with the indicated fields. If no match can be found, GetIndexForFields returns NULL.

Note:	When CaseInsensitive is true, descending indexes are considered even if they are case sensitive.


TIndexDefs::Update

TIndexDefs	See also 	Example

Refreshes index definitions in Items to reflect the current state of the table.

HIDESBASE void __fastcall Update(void);

Description

Call Update when the set of indexes for the table may have changed. Update refreshes the index definitions without opening the table.


TIndexDefs::~TIndexDefs

TIndexDefs

Frees the memory associated with the TIndexDefs object.

__fastcall virtual ~TIndexDefs(void) { }

Description

Do not call ~TIndexDefs directly. Instead, use the delete keyword on the object, which causes ~TIndexDefs to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection

TDefCollection


TIniFile

Hierarchy	Properties	Methods	See also

TIniFile is a low-level wrapper for the 16-bit Windows 3.x INI file system that enables storage and retrieval of application-specific information and settings in an application-specific INI file.

Unit

inifiles

Description

TIniFile enables handling the storage and retrieval of application-specific information and settings in a Windows 3.x INI file. The INI file text format is the standard way for Windows 3.x applications to store and retrieve application settings from session to session. An INI file stores information in logical groupings, called “sections.” For example, the WIN.INI file contains a section called “[Desktop]”. Within each section, actual data values are stored in named keys. Keys take the form:

The FileName passed to a TIniFile object when it is created is the name of the INI file the object accesses.

TIniFile provides a property and methods for reading from and writing to specific INI files, and for deleting entire sections in an INI file. In addition to these properties and methods, TIniFile inherits the methods of TCustomIniFile and TObject.

Note:	TIniFile is supported only for migration purposes and backward compatibility. Windows 95/NT replaces INI files with a system registry where all applications store and retrieve their settings. Applications that target Windows 95/NT should use the system registry instead of INI files. C++Builder provides two objects for handling the system registry. TRegistry encapsulates the system registry. TRegIniFile also encapsulates the registry, but provides an easier migration path for existing Windows 3.1 applications that are upgraded to Windows 95/NT.


TIniFile properties

TIniFile	Alphabetically	Legend

Derived from TCustomIniFile

FileName


TIniFile properties

TIniFile	By object	Legend

FileName


TIniFile::FileName

TIniFile	See also

Contains the name of the INI file from which to read and to which to write application-specific information.

__property System::AnsiString FileName = {read=FFileName};

Description

Use FileName to examine the name of the INI file used by the application for its application settings and information. The methods that read and write INI file information automatically handle opening and closing the file specified by FileName.

Note:	Usually INI files are stored in the \WINDOWS directory. To work with an INI file in another location, specify the full path name of the file in the FileName parameter passed to the Create method of TIniFile.


TIniFile methods

TIniFile	Alphabetically

In TIniFile

~TIniFile

DeleteKey

EraseSection

ReadSection

ReadSections

ReadSectionValues

ReadString

TIniFile

UpdateFile

WriteString

Derived from TCustomIniFile

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadTime

SectionExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteTime

ValueExists

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TIniFile methods

TIniFile	By object

~TIniFile

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DeleteKey

Dispatch

EraseSection

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

SectionExists

TIniFile

UpdateFile

ValueExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime


TIniFile::DeleteKey
 KTIniFile::DeleteKey

TIniFile	See also 	Example

Erases the data value associated with an INI file entry.

virtual void __fastcall DeleteKey(const System::AnsiString Section, const System::AnsiString Ident);

Description

Call DeleteKey to erase a data value associated with an INI file entry. Section is string containing the name of an INI file section, and Ident is a string containing the name of the key from for which to set a NULL value.

Note:	Attempting to erase a data value in a non-existent section or attempting to erase data from a non-existent key are not errors. In these cases, DeleteKey creates the section and key and sets its initial value to an empty value.


TIniFile::EraseSection

TIniFile	See also

Erases an entire section of an INI file.

virtual void __fastcall EraseSection(const System::AnsiString Section);

Description

Call EraseSection to remove a section, all its keys, and their data values from an INI file. Section identifies the INI file section to remove. If a section cannot be removed, an exception is raised.


TIniFile::ReadSection

TIniFile	See also

Reads all the key names from a specified section of an INI file into a string list.

virtual void __fastcall ReadSection(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSection to retrieve the names of all keys within a specified section of an INI file into a string list object.

Section identifies the section from which to retrieve a list of key names. Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object such as a string list, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TIniFile::ReadSections

TIniFile	See also

Reads the names of all sections in an INI file into a string list.

virtual void __fastcall ReadSections(Classes::TStrings* Strings);

Description

Call ReadSections to retrieve the names of all sections in an INI file into a string list object.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TIniFile::ReadSectionValues

TIniFile	See also 	Example

Reads the values from all keys within a section of an INI file into a string list.

virtual void __fastcall ReadSectionValues(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSectionValues to read the values from all keys within a specified section of an INI file into a string list object. Section identifies the section in the file from which to read key values. Strings is the string list object into which to read the values.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TIniFile::ReadString

TIniFile	See also	Example

Retrieves a string value from an INI file.

virtual System::AnsiString __fastcall ReadString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Default);

Description

Call ReadString to read a string value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the value. Default is the string value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TIniFile::UpdateFile

TIniFile	See also

Flushes buffered INI file data to disk.

virtual void __fastcall UpdateFile(void);

Description

•	Call UpdateFile to flush buffered reads from and writes to the INI file to disk. UpdateFile is useful under Windows95, but has no effect under Windows NT as NT does not buffer INI file reads and writes.


TIniFile::WriteString

TIniFile	See also 	Example

Writes a string value to an INI file.

virtual void __fastcall WriteString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Value);

Description

Call WriteString to write a string value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the string value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteString creates the section and key and sets its initial value to Value.


TIniFile::TIniFile

TIniFile

TIniFile creates a new TIniFile object.

__fastcall TIniFile(const System::AnsiString FileName) : Inifiles::TCustomIniFile(FileName) { }

Description

Call TIniFile to construct a TIniFile object for an application.

FileName specifies the name of the INI file to use.

Note	Usually INI files are stored in the \WINDOWS directory. To work with an INI file in another location, specify the full path name of the file in FileName.


TIniFile::~TIniFile

TIniFile

~TIniFile frees the memory associated with the TIniFile object.

__fastcall virtual ~TIniFile(void) { }

Description

Do not call ~TIniFile directly. Instead, use the delete keyword on the object, which causes ~TIniFile to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TCustomIniFile


TInplaceEdit

Hierarchy	Properties	Methods	See also

TInPlaceEdit provides text editing capabilities for grid controls.

Unit

grids

Description

TInPlaceEdit is a helper object tailored to work with grid controls. It provides a multiline editing window that appears in the appropriate cell of a grid control. TInPlaceEdit provides services so that the grid can influence the response of the control to user actions, and can move or resize the editing window as cells are moved or resized.

The TInPlaceEdit window has no border, so it does not stand out as a separate control. TInPlaceEdit is not a data-aware control, but can work with a data-aware grid such as TDBGrid, allowing the grid to fetch or post the text, and allowing the grid to impose a mask to limit the text of the edit control to data that is valid.


TInplaceEdit properties

TInplaceEdit	Alphabetically	Legend

In TInplaceEdit

Grid

Derived from TCustomMaskEdit

EditText

IsMasked

Text

Derived from TCustomEdit

CanUndo

Modified

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TInplaceEdit properties

TInplaceEdit	By object	Legend

Align

BoundsRect

Brush

CanUndo

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

EditText

Enabled

Grid

Handle

Height

HelpContext

Hint

IsMasked

Left

Modified

Name

Owner

Parent

ParentWindow

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TInplaceEdit::Grid

TInplaceEdit	See also

Specifies the grid object that owns and controls this TInplaceEdit.

__property TCustomGrid* Grid = {read=FGrid};

Description

Read Grid to obtain the grid object for which TInplaceEdit provides editing services. TInplaceEdit uses the Grid property so that it can receive information about the text to be edited and so that it can pass on relevant events.


TInplaceEdit methods

TInplaceEdit	Alphabetically	Legend

In TInplaceEdit

~TInplaceEdit

BoundsChanged

CreateParams

DblClick

Deselect

EditCanModify

Hide

Invalidate

KeyDown

KeyPress

KeyUp

Move

PosEqual

SetFocus

TInplaceEdit

UpdateContents

UpdateLoc

WndProc

Derived from TCustomMaskEdit

Clear

GetTextLen

ValidateEdit

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TInplaceEdit methods

TInplaceEdit	By object	Legend

~TInplaceEdit

Assign

BeginDrag

BoundsChanged

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CreateParams

CutToClipboard

DblClick

DefaultHandler

Deselect

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EditCanModify

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

KeyPress

KeyUp

MethodAddress

MethodName

Move

NewInstance

PaintTo

PasteFromClipboard

Perform

PosEqual

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TInplaceEdit

Undo

Update

UpdateContents

UpdateControlState

UpdateLoc

ValidateEdit

WndProc


TInplaceEdit::BoundsChanged

TInplaceEdit	See also

Indents the text area of the window slightly after the grid repositions the edit control.

virtual void __fastcall BoundsChanged(void);

Description

BoundsChanged re-initializes the editing window after the control has been moved or resized. It creates a slight indentation in the text formatting area so that the contents of the editor do not appear to crowd the edges of the cell.

BoundsChanged is exposed as a protected method so that derived objects can add further enhancements when the editing window changes size or location.


TInplaceEdit::TInplaceEdit

TInplaceEdit	See also

Creates an instance of TInplaceEdit.

__fastcall virtual TInplaceEdit(Classes::TComponent* AOwner);

__fastcall TInplaceEdit(HWND ParentWindow) : Mask::TCustomMaskEdit(ParentWindow) { }

Description

Do not create instances of TInplaceEdit. These are created automatically by the grid that uses the editor.

TInplaceEdit takes a single Component as a parameter to provide the editor with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. TInplaceEdit takes a window handle as a parameter to embed the editor in a non-VCL window. This syntax is not used for TInplaceEdit.

TInplaceEdit makes sure that the control has no border to provide a visual indication that the control exists.


TInplaceEdit::TInplaceEdit
TInplaceEdit::CreateParams

TInplaceEdit	See also

Initializes a window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it passes to CreateWindowHandle. TInplaceEdit overrides the inherited method to specify a multiline edit control.


TInplaceEdit::DblClick

TInplaceEdit	See also

Informs the grid when the user double-clicks in the edit window.

DYNAMIC void __fastcall DblClick(void);

Description

DblClick is called when the user double-clicks in the edit window. DblClick simply passes the event on to the grid. The grid must interpret and respond to the double-click. If the edit window needs to respond to the double-click, the grid must trigger the response by calling a method or setting a property of the TInplaceEdit.


TInplaceEdit::Deselect

TInplaceEdit	See also

Removes the selection from the edit window.

void __fastcall Deselect(void);

Description

Use Deselect to cause all text in the edit window to be unselected. Deselect simply changes the selection, it does not change the actual text.


TInplaceEdit::EditCanModify

TInplaceEdit	See also

Determines whether the user can edit the Text.

virtual bool __fastcall EditCanModify(void);

Description

EditCanModify is called automatically when the user tries to edit the value of Text. EditCanModify calls the CanEditModify method of the grid to determine whether the current cell of the grid should be edited. When EditCanModify returns true, the user is permitted to edit the text. When EditCanModify returns false, the user is prevented from editing the text.


TInplaceEdit::Hide

TInplaceEdit	See also

Hides the edit control window and moves input focus to the grid.

HIDESBASE void __fastcall Hide(void);

Description

Hide makes the edit control window invisible without destroying it. Hide also moves the input focus from the editor window to the grid, so that the invisible window does not swallow keyboard events.

The grid calls Hide to hide the edit window when changing out of edit mode. It also calls Hide when scrolling the cell that is being edited out of the grid window.


TInplaceEdit::Invalidate

TInplaceEdit	See also

Invalidates the edit window and the corresponding portion of the grid window.

HIDESBASE void __fastcall Invalidate(void);

Description

Invalidate ensures that the portion of the grid window under the edit control is invalidated at the same time as the edit window. This is important when the edit window is hidden or destroyed so that the grid window can repaint the cell that was covered by the edit window.


TInplaceEdit::KeyDown

TInplaceEdit	See also

Responds when the user presses a key.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

When the user presses a key, KeyDown checks whether the KeyDown event should be processed by the edit control or the grid. The Enter key is always passed on to the grid. The F2 key calls Deselect to remove the current selection. Navigation keystrokes are passed on to the grid when the movement cannot be accommodated within the text window. For example, if the user types Left when the cursor is already at the left edge of the edit window, the keystroke is passed to the grid which moves focus to the previous cell. If the cursor is in the middle of a line, the keystroke is processed by the edit window, which moves left a single character.

KeyDown calls the OnKeyDown event handler for the grid, if there is one, before calling the inherited KeyDown for the edit control.


TInplaceEdit::KeyPress

TInplaceEdit	See also

Responds when the user types a key.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

KeyPress allows the grid to handle the keystroke, and only processes keystrokes that the grid does not fully handle. If the grid is not in edit mode after handling the keystroke, KeyPress throws away the keystroke. Keystroke processes the Return Key and calls the inherited method to handle all other unprocessed keystrokes.

Pressing the Return key causes KeyPress to select all the text, unless it is already selected, in which case it causes KeyPress to deselect all the text.


TInplaceEdit::KeyUp

TInplaceEdit	See also

Responds when the user releases a key.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

DYNAMIC void __fastcall KeyUp(Word &Key, Classes::TShiftState Shift);

Description

The inplace edit control does not process the KeyUp event at all. It simply passes this event on to the grid, which may or may not process the event.


TInplaceEdit::Move

TInplaceEdit	See also

Changes the position of the edit window and repaints the contents.

void __fastcall Move(const Windows::TRect &Loc);

Description

The grid calls Move to move the edit window to the indicated rectangle when the corresponding cell moves or resizes. The position of Loc is relative to the grid’s client area.


TInplaceEdit::PosEqual

TInplaceEdit	See also

Indicates whether the edit window has the size and position indicated by Rect.

bool __fastcall PosEqual(const Windows::TRect &Rect);

Description

Use PosEqual to determine if the edit window occupies a particular rectangle, where Rect is given in global coordinates. PosEqual can be used to determine whether the inplace edit control represents a particular cell in the grid, by checking the bounding rectangle of the cell.


TInplaceEdit::SetFocus

TInplaceEdit	See also

Gives the editor window input focus if it is visible.

HIDESBASE void __fastcall SetFocus(void);

Description

Use SetFocus to cause keyboard events to go to the editor window. Focus will not move to the window if it is hidden by a call to the Hide method.


TInplaceEdit::UpdateContents

TInplaceEdit	See also

Sets the EditMask and Text properties to values specified by the grid.

virtual void __fastcall UpdateContents(void);

Description

UpdateContents calls the GetEditMask and GetEditText methods of the grid, and sets the EditMask and Text properties accordingly. UpdateContents allows the grid to bring up the inplace edit control with the contents of a particular cell, and to impose a mask to restrict the editor to valid input for the particular cell.


TInplaceEdit::UpdateLoc

TInplaceEdit	See also

Changes the position of the edit window but does not repaint the contents.

void __fastcall UpdateLoc(const Windows::TRect &Loc);

Description

The grid calls UpdateLoc to move the edit window when the grid is moved. Unlike the Move method, UpdateLoc does not invalidate the edit window to cause a repaint.


TInplaceEdit::WndProc

TInplaceEdit	See also

Supplements the inherited method to add special processing to some Windows messages.

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

WndProc is the first method that receives messages for a C++Builder control.

WndProc for TInplaceEdit passes focus events on to the grid. It calls the inherited method for all other Windows messages. WndProc converts mouse clicks to double clicks when the first click was received by the grid within the double-click time period.


TInplaceEdit::~TInplaceEdit

TInplaceEdit

Frees the memory associated with the TInplaceEdit object.

__fastcall virtual ~TInplaceEdit(void) { }

Description

Do not call ~TInplaceEdit. The creation and destruction of inplace edit controls is handled by the grid that uses them.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMaskEdit


TIntegerField

Hierarchy	Properties	Methods	Events	See also

TIntegerField represents a signed 32-bit integer field in a dataset.

Unit

db

Description

Integer fields can hold values in the range -2,147,483,648 to 2,147,483,647, and are frequently used to hold values that are large, signed whole numbers.

TIntegerField introduces new properties to convert between integer values and other data types, and to limit the range of valid integers that the field will permit. As a descendant of TNumericField, TIntegerField includes many properties, methods, and events that are useful for managing the value and properties of a numeric field in a database.

TIntegerField is the direct ancestor of three other field types that represent whole numbers: TAutoIncField, TSmallintField, and TWordField.


TIntegerField properties

TIntegerField	Alphabetically	Legend

In TIntegerField

AsFloat

AsInteger

AsString

AsVariant

DataSize

MaxValue

MinValue

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TIntegerField properties

TIntegerField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TIntegerField::AsFloat

TIntegerField	See also

Represents the value of the integer field as a floating-point value.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

Use AsFloat to

•	Assign the integer field value to a floating-point variable.

•	Round a floating-point value to an integer value and assign it to an integer field.

For example, this code assigns a floating-point value to an integer field value, rounding the value to 12:

MyIntegerField->AsFloat = 12.23;

To assign an integer field value to a floating-point value, use code similar to this:

FloatVariable = MyIntegerField->AsFloat;

If the value assigned to the field does not fall within the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TIntegerField::AsInteger

TIntegerField	See also 	Example

Represents the value of an integer field as a 32-bit integer.

__property int AsInteger = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

Use AsInteger to work with the value of an integer field as a 32-bit integer. Integer field components store and manipulate their values as 32-bit integers, so AsInteger is the same as the Value property.

Long integer values need no conversion, because the native storage format of an integer field is a 32-bit integer. Descendants of TIntegerField that represent other types of integer fields convert the value of the physical database field to a 32-bit integer for the AsInteger property.

If the value assigned to the field does not fall within the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TIntegerField::AsString

TIntegerField	See also 	Example

Represents the value of an integer field as a string.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Use AsString to

•	Assign the integer field value to string variable.

•	Assign a string value to the integer field.

For example, this code assigns a string value to an integer field value:

MyIntegerField->AsString = "27";

To assign an integer field value to a string, use code similar to this:

Edit1->Text = MyIntegerField->AsString;

If the string assigned to the field does not represent a valid integer value, an EDatabaseError exception is thrown. Also, if the assigned string does not convert to an integer value that falls within the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TIntegerField::AsVariant

TIntegerField	See also

Represents the value of an integer field as a Variant value.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the integer field value to variant variable.

•	Assign a variant value to the integer field.

Using variants is useful when you don't know the actual field type and don't want to use one of the other As... properties to convert the field value to another type.

If the value assigned to the field can’t be converted to a valid integer or does not fall within the range specified by the MinValue and MaxValue properties, an EDatabaseError exception is thrown.


TIntegerField::DataSize

TIntegerField	See also 	Example

Indicates the amount of memory needed to store the value of an integer field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store an integer field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For integer fields, DataSize is always 4. Some descendants of TIntegerField such as TSmallintField, represent database fields with smaller values of DataSize.


TIntegerField::MaxValue

TIntegerField	See also

Limits the maximum value in the integer field.

__property int MaxValue = {read=FMaxValue, write=SetMaxValue, default=0};

Description

Use MaxValue to get or set the maximum value that can be entered into the field. If a value greater than MaxValue is entered, an EDatabaseError exception is thrown.

If the value of MaxValue is 0, the integer field can have a value up to the maximum value that can be represented by the native database type. For 32-bit integer fields, this value is 2147483647.


TIntegerField::MinValue

TIntegerField	See also

Limits the minimum value in the integer field.

__property int MinValue = {read=FMinValue, write=SetMinValue, default=0};

Description

Use MinValue to get or set the minimum value that can be entered into the field. If a value smaller than MinValue is entered, an EDatabaseError exception is thrown.

If the value of MinValue is 0, the integer field can have a value as small as the native database type can represent. For 32-bit integer fields, this minimum value is -2147483648.


TIntegerField::Value

TIntegerField	See also

Represents the value of the integer field.

__property int Value = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

Use Value to read data directly from and write data directly to an integer field. Using the Value property is the same as using the AsInteger property. Use Value when you know the field component is a 32-bit integer field. Use AsInteger when working with a generic field component.


TIntegerField events

TIntegerField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TIntegerField events

TIntegerField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TIntegerField methods

TIntegerField	Alphabetically

In TIntegerField

~TIntegerField

TIntegerField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TIntegerField methods

TIntegerField	By object

~TIntegerField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TIntegerField

Validate


TIntegerField::TIntegerField

TIntegerField	See also

Creates an instance of TIntegerField.

__fastcall virtual TIntegerField(Classes::TComponent* AOwner);

Description

Do not call TIntegerField directly to create and initialize an instance of TIntegerField. Instead, use the new keyword, passing it an Owner that is responsible for freeing the integer field. It is seldom necessary to create integer fields, because an integer field component is instantiated automatically for all integer fields in a dataset.

After calling the parent object’s constructor, TIntegerField sets the DataType to ftInteger, the MinValue to -2147483648, and the MaxValue to 2147483647.


TIntegerField::~TIntegerField

TIntegerField

Frees the memory associated with the TIntegerField object.

__fastcall virtual ~TIntegerField(void) { }

Description

Do not call ~TIntegerField directly. Instead, use the delete keyword on the object, which causes ~TIntegerField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField


TInterfacedObject

Hierarchy	Properties	Methods

TInterfacedObject is a class that implements the IUnknown interface, and that can be used as a base for simple COM-compatible classes that benefit from having the IUnknown methods implmemented.

Unit

sysdefs.h

Description

TInterfacedObject is used as a base class for simple COM classes that do not have a class factory or a registered CLSID. This means that they must be instantiated by calling a constructor directly.

TInterfacedObject serves as a convenient base class for classes that implement interfaces because it implements the methods of IUnknown. Variables declared to be of type TInterfacedObject will have dynamic-binding, meaning that an instance of a descendent class can be assigned to that variable at runtime. This is because TInterfacedObject implements QueryInterface, which is called at runtime to query whether the instantiated object supports the requested interface. If it does then the descendent object will successfully be assigned to the variable. The same assignment of a descendent COM object, to a variable declared as a base class type, will generate a compile-time error if that base class does not implement IUnknown.

There is no class factory for TInterfacedObject.

Implemented methods of IUnknown

QueryInterface and AddRef, Release.


TInterfacedObject properties

TInterfacedObject	Alphabetically	Legend

In TInterfacedObject

RefCount


TInterfacedObject properties

TInterfacedObject	By object	Legend

RefCount


TInterfacedObject::RefCount

TInterfacedObject

Holds the reference count for the number of interface pointers that are currently dependent upon the COM object.

__property int RefCount = { read=FRefCount };

Description

RefCount defines the lifetime of the object. When RefCount is zero, the object is destroyed.

RefCount is incremented by calls to the implemented IUnknown method AddRef and decremented by the implemented IUnknown method Release.


TInterfacedObject methods

TInterfacedObject	Alphabetically

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TInterfacedObject methods

TInterfacedObject	By object

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


Accessibility

Read-only


Hierarchy

TObject


TISAPIApplication

Hierarchy	Properties	Methods	See also

TISAPIApplication encapsulates an ISAPI or NSAPI server application.

Unit

isapiapp

Description

TISAPIApplication provides the fundamental behavior of an ISAPI or NSAPI server application. The HTTP server calls the methods of TISAPIApplication when it receives an HTTP request message. TISAPIApplication creates a thread to manage the request message, and a creates a new instance of the Web module for that thread, or reuses an old instance that was deactivated after a previous response was sent.

TISAPIApplication creates TISAPIRequest and TISAPIResponse objects to represent the request message and any response that should be sent in return, passes these to the dispatcher so that the response can be filled in, and sends the response if it was not already sent by a TWebActionItem.

Each ISAPI server project automatically declares an Application variable of type TISAPIApplication as the instance of the application. Because of this, do not include Forms.hpp in an ISAPI application, because the Forms header declares a conflicting Application variable of type TApplication. Every ISAPI server application must include ISAPIApp.hpp and link with ISAPIApp.dcu.

To work with a CGI server, use the TCGIApplication object instead.


TISAPIApplication properties

TISAPIApplication	Alphabetically	Legend

Derived from TWebApplication

ActiveCount

CacheConnections

InactiveCount

MaxConnections

Title

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TISAPIApplication properties

TISAPIApplication	By object	Legend

ActiveCount

CacheConnections

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

InactiveCount

MaxConnections

Name

Owner

Tag

Title

VCLComObject


TISAPIApplication methods

TISAPIApplication	Alphabetically

In TISAPIApplication

~TISAPIApplication

GetExtensionVersion

HttpExtensionProc

TerminateExtension

TISAPIApplication

Derived from TWebApplication

CreateForm

Initialize

Run

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TISAPIApplication methods

TISAPIApplication	By object

~TISAPIApplication

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateForm

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetExtensionVersion

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

HttpExtensionProc

InheritsFrom

Initialize

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

Run

SafeCallException

TerminateExtension

TISAPIApplication


TISAPIApplication::GetExtensionVersion

TISAPIApplication	See also

Returns the application name and version number.

BOOL __fastcall GetExtensionVersion(Isapi2::THSE_VERSION_INFO &Ver);

Description

The HTTP server calls GetExtensionVersion to obtain the application name and version number. GetExtensionVersion returns the version number for the HTTP functions in the runtime library, and the Title property of the ISAPI application object.


TISAPIApplication::HttpExtensionProc

TISAPIApplication	See also

Responds to an HTTP request message.

int __fastcall HttpExtensionProc(Isapi2::TEXTENSION_CONTROL_BLOCK &ECB);

Description

The HTTP server calls HttpExtensionProc when it receives an HTTP request message. HttpExtensionProc creates the TISAPIRequest and TISAPIResponse objects for the HTTP request message, and calls the HandleRequest message so that the response can be filled out and sent. Finally, HttpExtensionProc frees the request and response objects.

If the response is filled out and sent, HttpExtensionProc returns HSE_STATUS_SUCCESS. Otherwise it returns HSE_STATUS_ERROR.


TISAPIApplication::TerminateExtension

TISAPIApplication

Returns true.

BOOL __fastcall TerminateExtension(int dwFlags);

Description

The HTTP server calls TerminateExtension when it wants to shut down the ISAPI application. TerminateExtension always returns true, allowing the server to shut down.


TISAPIApplication::TISAPIApplication

TISAPIApplication

Creates a new TISAPIApplication object.

__fastcall virtual TISAPIApplication(Classes::TComponent* AOwner) : Httpapp::TWebApplication(AOwner) { }

Description

Do not create instances of TISAPIApplication. A global instance of TISAPIApplication, called Application, is automatically created for ISAPI server applications.


TISAPIApplication::~TISAPIApplication

TISAPIApplication

~TISAPIApplication frees the memory associated with the TISAPIApplication object.

__fastcall virtual ~TISAPIApplication(void) { }

Description

Do not call ~TISAPIApplication. The global TISAPIApplication instance is deleted automatically when the application terminates.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TWebApplication


TISAPIRequest

Hierarchy	Properties	Methods	See also

TISAPIRequest represents client request information that is passed to a server application DLL.

Unit

isapiapp

Description

Use TISAPIRequest to interpret a client request to a server application DLL.

ISAPI application objects create TISAPIRequest objects to capture client requests. The properties of the TISAPIRequest objects are obtained from the Web server. The ISAPI application uses TISAPIRequest objects to create corresponding TISAPIResponse objects. The TWebDispatcher for the application then invokes the TWebActionItem that is associated with the path portion of the URL of the TISAPIRequest object.


TISAPIRequest properties

TISAPIRequest	Alphabetically	Legend

In TISAPIRequest

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentLength

ContentType

ContentVersion

Cookie

Date

DerivedFrom

ECB

Expires

From

Host

IfModifiedSince

Method

PathInfo

PathTranslated

ProtocolVersion

Query

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent

Derived from TWebRequest

ContentFields

CookieFields

MethodType

QueryFields


TISAPIRequest properties

TISAPIRequest	By object	Legend

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentFields

ContentLength

ContentType

ContentVersion

Cookie

CookieFields

Date

DerivedFrom

ECB

Expires

From

Host

IfModifiedSince

Method

MethodType

PathInfo

PathTranslated

ProtocolVersion

Query

QueryFields

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent


TISAPIRequest::Accept

TISAPIRequest	See also

Indicates the value of the Accept header of the HTTP request message.

__property System::AnsiString Accept = {read=GetStringVariable, index=8};

Description

Read Accept to determine the media types the Web client can accept in response to the request. Not every HTTP request message has an Accept header. If the Accept property is not set, then any media type is potentially acceptable in the response.

Accept headers usually indicate that the response should be limited to a small set of desired types. For example, a Web client requesting an audio response might produce a TISAPIRequest object with Accept set to the following string:

audio/*; q=0.2, audio/basic

This request indicates that the preferred response media type is audio/basic, but that any audio type is acceptable if it is the best available after an 80% mark-down in quality.

For information on the format of Accept headers, see the current Internet standards documentation.


TISAPIRequest::Authorization

TISAPIRequest	See also

Indicates the value of the Authorization header of the HTTP request message.

__property System::AnsiString Authorization = {read=GetStringVariable, index=28};

Description

Read Authorization to check whether the client that sent the request message has provided the correct authentication information. Authorization allows the Web application to provided limited access to the resource specified by the URL property.

For more information about HTTP authentication schemes, see the Internet standards documentation.


TISAPIRequest::CacheControl

TISAPIRequest 	See also

Indicates the value of the Cache-Control header of the HTTP request message.

__property System::AnsiString CacheControl = {read=GetStringVariable, index=6};

Description

Read CacheControl to determine any Web client directives that must be obeyed by all caching mechanisms along the request/response chain. The CacheControl directives of the HTTP request do not need to apply to the corresponding HTTP response.

The HTTP 1.1 standard defines the following directives for CacheControl:

Value	Meaning

no-cache	The request may not be cached. The Web server validates the request before the TISAPIRequest object is created.

no-store	The request contains sensitive information and may not be stored on any permanent medium such as a back-up tape. If the request is stored temporarily in a file, the file must be deleted.

max-age=ss	The request is considered invalid if it is older than ss seconds. This directive takes precedence over the Expires property, even if Expires is more restrictive. Invalid requests are validated by the Web server before the TISAPIRequest object is created.

max-stale or

max-stale=ss	The client is willing to accept a response that has exceeded it’s expiration time. The max-stale directive can optionally specify the number of seconds by which the response can exceed it’s expiration time.

min-fresh=ss	The client is not willing to accept a response that expires in less than ss seconds.


TISAPIRequest::Connection

TISAPIRequest	See also

Indicates the value of the Connection header of the HTTP request message.

__property System::AnsiString Connection = {read=GetStringVariable, index=26};

Description

Read Connection to determine the options requested by the Web client for its connection to the server application. The HTTP 1.1 standard specifies only one value for the Connection header. If the value of Connection is close, then the connection should be closed after the completion of the response.


TISAPIRequest::Content

TISAPIRequest	See also

Represents the unparsed contents of the HTTP request message.

__property System::AnsiString Content = {read=GetStringVariable, index=25};

Description

Use Content to read the contents of an HTTP request message that is sending information to the server. The value of Content depends on the Method of the HTTP request. When the Method is POST, Content is the unparsed string giving the values to be posted with their associated fields. When the Method is PUT, Content is the value that should replace the URL given by the URL property.

Note:	When the Method is POST, the parsed version of the post request is available in the ContentFields property.


TISAPIRequest::ContentEncoding

TISAPIRequest	See also

Indicates the value of the Content-Encoding header of the HTTP request message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, index=14};

Description

Read ContentEncoding to determine what encoding mechanisms, if any, have been applied to the Content of the HTTP request. The encoding mechanisms are listed in the order in which they were applied by the Web client, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding scheme used to transfer extended ASCII characters over the net.

Reverse the ContentEncoding mechanisms to decode the Content into the form indicated by the ContentType property.


TISAPIRequest::ContentLength

TISAPIRequest	See also

Indicates the value of the Content-Length header of the HTTP request message.

__property int ContentLength = {read=GetIntegerVariable, index=16, nodefault};

Description

Read the ContentLength property to determine the length of the Content property. ContentLength allows an application to determine the end of the Content property when the ContentType is not text/html. A ContentLength of 0 indicates that the length of the Content property is not determined, either because the request does not include any Content, or because the Web client did not know the length.

Note:	The length of the Content may be less than ContentLength when the Content is passed by chunked transfer coding.


TISAPIRequest::ContentType

TISAPIRequest	See also

Indicates the value of the Content-Type header of the HTTP request message.

__property System::AnsiString ContentType = {read=GetStringVariable, index=15};

Description

Read ContentType to determine the media type of the Content of the HTTP request message. The ContentType is a string of the form Type/SubType.

Most HTTP requests do not require any Content at all. For most requests with a Method that requires a value for Content, the ContentType is text/html. However, HTTP requests for server-specific values of Method can use any media type appropriate to the request.


TISAPIRequest::ContentVersion

TISAPIRequest	See also

Indicates the value of the Content-Version header of the HTTP request message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, index=17};

Description

Read ContentVersion to determine the version of the Content of the HTTP request message. Most HTTP requests do not require any Content at all. When the Method requires a value for Content, the ContentVersion may be set to indicate the version of the source of that content. The format of the ContentVersion depends on the ContentType of the request.


TISAPIRequest::Cookie

TISAPIRequest	See also

Indicates the value of the Cookie header of the HTTP request message.

__property System::AnsiString Cookie = {read=GetStringVariable, index=27};

Description

Use Cookie to read the “cookie” strings provided in the Web client request. Cookie strings are generally used to track state information in a Web application. Cookie is the unparsed value of the Cookie header. The Cookie header can include multiple fields separated by semicolons. Use the CookieFields property to work with the Cookie header on a field-by-field basis.


TISAPIRequest::Date

TISAPIRequest 	See also

Indicates the value of the Date header of the HTTP request message.

__property System::TDateTime Date = {read=GetDateVariable, index=7};

Description

Read Date to determine the date and time at which the HTTP request message originated. Date can be used to determine whether the Content of the request is still valid. The value of Date is translated into local time as specified in the Windows Control Panel from the time units set by the Web client.

For example, if an HTTP request message specifies a MethodType of mtPost, and Date is older than the most recent values of the fields that are being posted, the server application may return a status code that indicates an error rather than overwriting more recent values.

Date is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TISAPIRequest::DerivedFrom

TISAPIRequest	See also

Indicates the value of the Derived-From header of the HTTP request message.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, index=18};

Description

Read DerivedFrom to determine the URI where the value of Content originated. DerivedFrom is only meaningful when the request includes a Content property and the Content did not originate with the Web client.


TISAPIRequest.ECB
TISAPIRequest::ECB

TISAPIRequest	See also

Indicates the extension control block structure used by the server application DLL to communicate with the Web server.

__property Isapi2::PEXTENSION_CONTROL_BLOCK ECB = {read=FECB};

Description

Read ECB to gain direct access to the extension control block that the server application DLL uses to represent the client request message. Most applications will not need to use the ECB property because the header fields values can be read using the GetFieldByName method.


TISAPIRequest::Expires

TISAPIRequest 	See also

Indicates the value of the Expires header of the HTTP request message.

__property System::TDateTime Expires = {read=GetDateVariable, index=19};

Description

Use Expires to determine whether the request is “stale”. Expires is the date and time at which the request becomes invalid. The value of Expires is translated into local time as specified in the Windows Control Panel from the time units set by the Web client.

If the request has a CacheControl value with a max-age directive, the max-age directive overrides the value of Expires.

Expires is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TISAPIRequest::From

TISAPIRequest	See also

Indicates the value of the From header of the HTTP request message.

__property System::AnsiString From = {read=GetStringVariable, index=9};

Description

Read From to determine the Internet e-mail address of the human user for whom the Web client sent the HTTP request message. This value can be used for logging purposes, or to contact the originator of the request if problems occur.


TISAPIRequest::Host

TISAPIRequest	See also

Indicates the value of the Host header of the HTTP request message.

__property System::AnsiString Host = {read=GetStringVariable, index=10};

Description

Read Host to determine the Internet host and port number of resource being requested. For example, if the client request specifies the following URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

the value of Host would be

www.TSite.com

The value of Host can be used to differentiate between internally ambiguous URLs, such as the root “/” URL of a server for multiple host names on a single IP address.


TISAPIRequest::IfModifiedSince

TISAPIRequest 	See also

Indicates the value of the If-Modified-Since header of the HTTP request message.

__property System::TDateTime IfModifiedSince = {read=GetDateVariable, index=11};

Description

Read IfModifiedSince on a request with a MethodType of mtGet to determine whether the request is conditional. If the information requested by the Web client was not modified since the time indicated by IfModifiedSince, the response should be a not modified error rather than the information indicated by the URL property.

The value of IfModifiedSince is given according to the local clock as specified in the Windows Control Panel, not the clock of the Web client.

IfModifiedSince is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TISAPIRequest::Method

TISAPIRequest	See also

Indicates the value of the Method header of the HTTP request message.

__property System::AnsiString Method = {read=GetStringVariable, index=0};

Description

Read Method to determine the method that is requested by the Web client. The HTTP 1.1 standard defines the following methods

Value	Meaning

OPTIONS	A request for information about available communication options.

GET	A request for the information identified by the URL property.

HEAD	A request for information about the properties of the HTTP response, but not for the content of the response.

POST	A request for the server application to post the data included in the Content property, as appropriate.

PUT	A request for the server application to replace the resource indicated by the URL property with the data included in the Content property.

DELETE	A request for the server application to delete or hide the resource identified by the URL property.

TRACE	A request for the server application to send a loop-back to confirm receipt of the request.

The Method property may indicate any other method that the Web client requests of the server. If the Method can’t be matched to the Allow property of a TISAPIResponse object, the request can’t be serviced.

The MethodType property indicates whether the value of Method is GET, HEAD, POST, PUT, or one of the other strings. When possible, use MethodType instead of the Method property to save the overhead of string comparison.

Note:	An HTTP application does not need to service all method types. However, there must be a response for the GET and HEAD method requests.


TISAPIRequest::PathInfo

TISAPIRequest	See also

Indicates the path information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString PathInfo = {read=GetStringVariable, index=4};

Description

Read PathInfo to determine the path on the server machine where the target of the request is found. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the PathInfo portion is

/mammals

The TWebDispatcher object uses the PathInfo to identify the appropriate TWebActionItem for servicing the request message.


TISAPIRequest::PathTranslated

TISAPIRequest	See also

Represents a translation of the PathInfo property to a fully qualified path on the Web server.

__property System::AnsiString PathTranslated = {read=GetStringVariable, index=5};

Description

Use PathTranslated to refer to the location of the target of the request in an HTTP response.


TISAPIRequest::ProtocolVersion

TISAPIRequest	See also

Indicates the version number of the HTTP protocol specified in the initial header of the HTTP request message.

__property System::AnsiString ProtocolVersion = {read=GetStringVariable, index=1};

Description

Use ProtocolVersion to determine the protocol used by the Web client when generating the HTTP request message.

Some properties of the HTTP request may be interpreted differently depending on the ProtocolVersion. For example, if ProtocolVersion is 1.0, then the connection should not be considered persistent, even if the Connection property does not specify the close option.


TISAPIRequest::Query

TISAPIRequest	See also

Represents the value of the query information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString Query = {read=GetStringVariable, index=3};

Description

Read Query to determine the details of a query specified in the URL of the Web client request. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the Query portion is

animal=dog&color=black

Query is the unparsed query portion of the URL. The query may include multiple fields separated by ampersands. Use the QueryFields property to work with the query on a field-by-field basis.


TISAPIRequest::Referer

TISAPIRequest	See also

Indicates the value of the Referer header of the HTTP request message.

__property System::AnsiString Referer = {read=GetStringVariable, index=12};

Description

Read Referer to determine the URI of the resource where the HTTP request message originated. Referer allows the server application to generate back-links to the source of the request. If Referer is a partial URI, it should be interpreted as a relative path to the URL property.

The Referer property is not set when the URL of the HTTP request was obtained from a source that does not have its own URI, such as input from the user keyboard.


TISAPIRequest::RemoteAddr

TISAPIRequest	See also

Indicates the remote IP address of the client associated with the HTTP request message.

__property System::AnsiString RemoteAddr = {read=GetStringVariable, index=21};

Description

Read RemoteAddr to obtain the IP address of the source of the Web client request.


TISAPIRequest::RemoteHost

TISAPIRequest	See also

Indicates the fully qualified reverse domain lookup of the client that sent the request message.

__property System::AnsiString RemoteHost = {read=GetStringVariable, index=22};

Description

Use RemoteHost to compose URI values for back-links to the source of the request when the Referer property is not specified. RemoteHost does not include any path information.


TISAPIRequest::ScriptName

TISAPIRequest	See also

Indicates the value of the script information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString ScriptName = {read=GetStringVariable, index=23};

Description

Read ScriptName to determine the full path to the Web server application specified by the client request. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the ScriptName portion is

/art/gallery


TISAPIRequest::ServerPort

TISAPIRequest	See also

Indicates the port number of the port on the Web server that received the request message.

__property int ServerPort = {read=GetIntegerVariable, index=24, nodefault};

Description

Read ServerPort to determine the number of the port used in the connection to the Web server. The Host property will include the ServerPort if it is specified as part of the URL for the client request.


TISAPIRequest::Title

TISAPIRequest	See also

Indicates the value of the Title header of the HTTP request message.

__property System::AnsiString Title = {read=GetStringVariable, index=20};

Description

Read Title to determine the Title of the information requested in the Web client request.


TISAPIRequest.URL

TISAPIRequest	See also

Indicates the Uniform Resource Identifier (URI) specified by the request message to identify the target of the request.

__property System::AnsiString URL = {read=GetStringVariable, index=2};

Description

Use the URL property to identify the resource the Web client identifies as the target of the request message. URL may be an HTML page to return, a resource to be created or deleted, or an object that provides some other service for the Web client.

The TISAPIRequest object parses the URL into its constituent parts, yielding the Host property, the ScriptName property, the PathInfo property, and the Query property.

Note:	Usually the URL property is a Uniform Resource Locator (URL) that can be parsed into host, script, path, and query portions. However, it is possible for HTTP request messages to specify the target in more general terms, as a Uniform Resource Identifier (URI).


TISAPIRequest::UserAgent

TISAPIRequest	See also

Indicates the value of the User-Agent header of the HTTP request message.

__property System::AnsiString UserAgent = {read=GetStringVariable, index=13};

Description

Read UserAgent to obtain information about the user agent originating the client request. Use the UserAgent information for statistical purposes, for tracing protocol violations, and for tailoring responses to known limitations of specific applications that generate client requests. The UserAgent string contains one or more descriptors, in order of significance. Each descriptor gives the name of the product or application that generated the request, or a comment about the user agent.


TISAPIRequest methods

TISAPIRequest	Alphabetically	Legend

In TISAPIRequest

~TISAPIRequest

GetDateVariable

GetFieldByName

GetIntegerVariable

GetStringVariable

ReadClient

ReadString

TISAPIRequest

TranslateURI

WriteClient

WriteString

Derived from TWebRequest

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TISAPIRequest methods

TISAPIRequest	By object	Legend

~TISAPIRequest

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

FieldAddress

Free

FreeInstance

GetDateVariable

GetFieldByName

GetIntegerVariable

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadClient

ReadString

SafeCallException

TISAPIRequest

TranslateURI

WriteClient

WriteString


TISAPIRequest::TISAPIRequest

TISAPIRequest	See also

Creates an instance of TISAPIRequest to represent the request message information contained in the AECB parameter.

__fastcall TISAPIRequest(Isapi2::PEXTENSION_CONTROL_BLOCK AECB);

Description

Applications don’t need to call TISAPIRequest to instantiate an ISAPI request object. TISAPIApplication creates a TISAPIRequest object whenever it receives a client request.


TISAPIRequest::GetDateVariable

TISAPIRequest	See also

Extracts a date value from the extension control block.

virtual System::TDateTime __fastcall GetDateVariable(int Index);

Description

GetDateVariable reads date-time values from the extension control block specified by the ECB property. The ISAPI request object uses GetDateVariable to access the properties that represent dates from the HTTP request headers.


TISAPIRequest::GetFieldByName

TISAPIRequest	See also

Returns the value of the HTTP header variable specified by the Name parameter.

virtual System::AnsiString __fastcall GetFieldByName(const System::AnsiString Name);

Description

Use GetFieldByName to read the value of an HTTP header variable that is not surfaced as one of the properties of TISAPIRequest. For information on possible HTTP request header variables, see the current Internet standards documents.


TISAPIRequest::GetIntegerVariable

TISAPIRequest	See also

Extracts an integer value from the extension control block.

virtual int __fastcall GetIntegerVariable(int Index);

Description

GetIntegerVariable reads integer values from the extension control block specified by the ECB property. The ISAPI request object uses GetIntegerVariable to access the properties that represent integers from the HTTP request headers.


TISAPIRequest::GetStringVariable

TISAPIRequest	See also

Extracts a string value from the extension control block.

virtual System::AnsiString __fastcall GetStringVariable(int Index);

Description

GetStringVariable reads string values from the extension control block specified by the ECB property. The ISAPI request object uses GetStringVariable to access the properties that represent strings from the HTTP request headers.


TISAPIRequest::ReadClient

TISAPIRequest	See also

Reads Count bytes from the HTTP request into Buffer.

virtual int __fastcall ReadClient(void *Buffer, int Count);

Description

Use ReadClient to load a chunk of information from the contents of an HTTP request into a buffer. ReadClient allows the server application to get the next chunk of information when the content of the request message is too large for the Content property. ReadClient returns the number of bytes actually read. If no more content is available, ReadClient returns -1.


TISAPIRequest::ReadString

TISAPIRequest	See also

Reads Count bytes from the HTTP request into a string.

virtual System::AnsiString __fastcall ReadString(int Count);

Description

Use ReadString to load the next chunk of content information form the HTTP request into a string. ReadString allows the server application to get the next chunk of information when the content of the request message is too large for the Content property.


TISAPIRequest::TranslateURI

TISAPIRequest	See also

Translates a Uniform Resource Identifier (URI) into the internal representation of a location on the server.

virtual System::AnsiString __fastcall TranslateURI(const System::AnsiString URI);

Description

Use TranslateURI is used to translate the URI specified in a client request into a format that can be used by the server application.


TISAPIRequest::WriteClient

TISAPIRequest	See also

Writes Count bytes from Buffer back to the HTTP client.

virtual int __fastcall WriteClient(void *Buffer, int Count);

Description

Use WriteClient to write the contents of a response back to the Web client.


TISAPIRequest::WriteString

TISAPIRequest	See also

Writes the string AString back to the HTTP client.

virtual bool __fastcall WriteString(const System::AnsiString AString);

Description

Use WriteString to write the contents of a response back to the Web client.


Accessibility

Read-only


TISAPIRequest::~TISAPIRequest

TISAPIRequest

Frees the memory associated with the TISAPIRequest object.

__fastcall virtual ~TISAPIRequest(void) { }

Description

Do not call ~TISAPIRequest directly. Instead, use the delete keyword on the object, which causes ~TISAPIRequest to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TWebRequest


TISAPIResponse

Hierarchy	Properties	Methods	See also

TISAPIResponse represents HTTP messages sent by an ISAPI application in response to an HTTP request message.

Unit

isapiapp

Description

Use TISAPIResponse to specify the response to an HTTP request message.

An ISAPI application creates a TISAPIResponse object based on the TISAPIRequest object for an incoming HTTP request message. TWebDispatcher then passes the TISAPIResponse object to the TWebActionItem associated with the TISAPIRequest object. The TWebActionItem sets the properties of the TISAPIResponse object.


TISAPIResponse properties

TISAPIResponse	Alphabetically	Legend

In TISAPIResponse

Allow

Content

ContentEncoding

ContentLength

ContentType

ContentVersion

Date

DerivedFrom

Expires

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate

Derived from TWebResponse

ContentStream

Cookies

CustomHeaders

HTTPRequest


TISAPIResponse properties

TISAPIResponse	By object	Legend

Allow

Content

ContentEncoding

ContentLength

ContentStream

ContentType

ContentVersion

Cookies

CustomHeaders

Date

DerivedFrom

Expires

HTTPRequest

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate


TISAPIResponse::Allow

TISAPIResponse	See also

Lists the HTTP request methods that the application can service.

__property System::AnsiString Allow = {read=GetStringVariable, write=SetStringVariable, index=5};

Description

Use Allow to indicate what type of request methods the server application can respond to for the URL specified in HTTPRequest. Allow is a string of method names, separated by commas. The method names can include any pre-defined methods from the HTTP standard, or any additional methods implemented by the server application. At a minimum, the TISAPIResponse object must allow GET and HEAD requests.


TISAPIResponse::Content

TISAPIResponse	See also 	Example

Specifies the information sent to the web client in response to an HTTP request message.

__property System::AnsiString Content = {read=GetContent, write=SetContent};

Description

Use Content to send requested information to the web client. Not every HTTP request message requires content to be returned. For example, responses to requests with a Method of OPTIONS, HEAD, POST, PUT, DELETE, or TRACE should not include any Content. In all these cases, the response information is contained entirely in the response header, which is built from the other properties of the TISAPIResponse object.

The response content can be a string of HTML commands, the name of an HTML file, graphic content such as a bit-stream, or any other MIME content type.

Note:	If the ContentStream property is set, it supersedes the value of the Content property. If both Content and ContentStream are set, the web client is sent the value of the ContentStream, not the value of the Content property.


TISAPIResponse::ContentEncoding

TISAPIResponse	See also

Lists the mechanisms, if any, used to encode the content of the HTTP response message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, write=SetStringVariable, index=7}

Description

Set ContentEncoding when the value of the Content has been encoded before it is sent to the web client. The encoding mechanisms are listed in the order in which they are applied, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding method used to transfer extended-ascii characters over the net.


TISAPIResponse::ContentLength

TISAPIResponse	See also

Specifies the length, in bytes, of the Content property.

__property int ContentLength = {read=GetIntegerVariable, write=SetIntegerVariable, index=0, nodefault};

Description

Set ContentLength to the length of the Content property, if it is known. If the length of the Content property is unknown, or if the HTTP response message does not include any content, set ContentLength to 0. Web clients use the ContentLength when reading the contents of the HTTP response message.

If the contents of the response message are taken from a stream, the value of ContentLength is set from the stream.


TISAPIResponse::ContentType

TISAPIResponse	See also

Indicates the media type of the Content of the HTTP response message.

__property System::AnsiString ContentType = {read=GetStringVariable, write=SetStringVariable, index=8};

Description

Set ContentType to indicate the media type of the Content of the HTTP response message. The value of ContentType must specify a valid MIME content type. The ContentType string has the form Type/SubType.

For example, if the response message sends a string of HTML commands to the web client in response to a GET request, the ContentType is text/html.

Note:	If the HTTP request message includes an Accept header, ContentType should be one of the content types listed in the TISAPIRequest::Accept property.


TISAPIResponse::ContentVersion

TISAPIResponse	See also

Indicates the version associated with the Content of the HTTP response message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, write=SetStringVariable, index=9};

Description

Use ContentVersion to specify a version associated with the Content of the HTTP response. The meaning of ContentVersion depends on the type of information that is sent in the HTTP response. For example, if the Content of the HTTP response has a ContentType of text/html, ContentVersion would be the version of HTML used.

Server applications that introduce meanings for the ContentVersion property should document the interpretation they assign to ContentVersion.


TISAPIResponse::Date

TISAPIResponse 	See also

Specifies the time and date when the HTTP response message is sent to the web client.

__property System::TDateTime Date = {read=GetDateVariable, write=SetDateVariable, index=0};

Description

Set Date to the current date and time immediately before sending the HTTP response message to the web client. Date is used by the web client to determine the age of the information returned.

Date is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TISAPIResponse::DerivedFrom

TISAPIResponse	See also

Specifies the URI of the resource where the Content of the HTTP response originated.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, write=SetStringVariable, index=10};

Description

Set DerivedFrom to the URI where the value of Content originates. It is especially important to set DerivedFrom when the Content of the HTTP response did not originate from the resource indicated by the URL property of the HTTP request message.


TISAPIResponse::Expires

TISAPIResponse 	See also

Specifies the date and time after which the Content of the HTTP response message should be considered invalid.

__property System::TDateTime Expires = {read=GetDateVariable, write=SetDateVariable, index=1};

Description

Set Expires when the Content of the HTTP response message contains information that may become invalid with the passage of time. Setting an Expires value does not imply that the information or its source will necessarily change or cease to exist when the Expires date and time is reached. Web clients are simply warned to check the freshness of the information after the Expires date and time.

The value of Expires is specified in the local time of the machine. The HTTP response message translates this value to the date encoding used by HTTP.

Expires is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TISAPIResponse::LastModified

TISAPIResponse 	See also

Indicates the date and time that the value of the Content property was last updated.

__property System::TDateTime LastModified = {read=GetDateVariable, write=SetDateVariable, index=2};

Description

Set LastModified to indicate the last time the Content of the HTTP response was modified. This allows web clients to determine whether their local version of that information is up-to-date. When the HTTP request is a HEAD message, this may allow the web client and server to skip a potentially expensive transfer of information.

The value of LastModified is specified in the local time of the machine. The HTTP response message translates this value to the date encoding used by HTTP.

LastModified is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TISAPIResponse::Location

TISAPIResponse	See also

Specifies the URI of a resource the web client should point to for the completion of its request.

__property System::AnsiString Location = {read=GetStringVariable, write=SetStringVariable, index=6};

Description

Set Location when creating a new resource in response to the HTTP request message, or when the servicing of the response must be delegated to another URI than the one specified in the HTTP request message.


TISAPIResponse::LogMessage

TISAPIResponse	See also

Specifies a descriptive string included in the response message for event logging purposes.

__property System::AnsiString LogMessage = {read=GetLogMessage, write=SetLogMessage};

Description

Set LogMessage to a description of the action carried out by the TWebActionItem object that services this HTTP response. Usually, LogMessage includes the URI that handled the HTTP request message, along with date and time information.


TISAPIResponse::Realm

TISAPIResponse	See also

Specifies the set of protected-access URIs that includes the URL specified by the request message.

__property System::AnsiString Realm = {read=GetStringVariable, write=SetStringVariable, index=4};

Description

Set Realm when the HTTP response message returns 401 (Unauthorized) or 402 (Payment required). Realm is the name of a set of URIs that require a password or payment before the web client can access them. All the URIs in the realm, including the URL specified in the HTTP request message, are made available as soon as the web client provides the password or payment for the realm. The server application should keep track, internally, of the passwords or payments the client has provided, using the client information provided by the TISAPIRequest object.


TISAPIResponse::ReasonString

TISAPIResponse	See also

Indicates the status of the response to the web client request in a human-readable format.

__property System::AnsiString ReasonString = {read=GetStringVariable, write=SetStringVariable, index=1};

Description

Set ReasonString to inform the human web client of the success or failure of the HTTP request message. Each reason string is associated with a 3-digit status code whose value indicates the status of the response. The HTTP standard defines a number of stock status codes and corresponding reason strings. In addition, server applications can define new reason strings and associate them with unused status codes.


TISAPIResponse::Server

TISAPIResponse	See also

Provides information about the software used by the server application to handle the request.

__property System::AnsiString Server = {read=GetStringVariable, write=SetStringVariable, index=2};

Description

Set Server to a string giving the name and version number of the application that provides the Content of the HTTP response message. The value of Server can contain multiple product identifiers and comments, listed in order of significance and separated by spaces. Product identifiers take the form ProductName/VersionNumber.


TISAPIResponse::StatusCode
 KTISAPIResponse::StatusCode

TISAPIResponse	See also

Indicates the status of the response to the HTTP request message as a 3-digit integer.

__property int StatusCode = {read=GetStatusCode, write=SetStatusCode, nodefault};

Description

Set StatusCode to inform the web client the status of the HTTP request message. Status codes are standard return values that can be interpreted by all web clients. Each status code has a corresponding reason string that provides a human web client with a more understandable indication of the status.

The following tables lists the available status codes and their corresponding reason strings.

StatusCode	ReasonString

100	Continue

101	Switching Protocols

200	OK

201	Created

202	Accepted

203	Non-Authoritative Information

204	No Content

205	Reset Content

206	Partial Content

300	Multiple Choices

301	Moved Permanently

302	Moved Temporarily

303	See Other

304	Not Modified

305	Use Proxy

400	Bad Request

401	Unauthorized

402	Payment Required

403	Forbidden

404	Not Found

405	Method Not Allowed

406	Not Acceptable

407	Proxy Authentication Required

408	Request Time-out

409	Conflict

410	Gone

411	Length Required

412	Precondition Failed

413	Request Entity Too Large

414	Request-URI Too Large

415	Unsupported Media Type

500	Internal Server Error

501	Not Implemented

502	Bad Gateway

503	Service Unavailable

504	Gateway Time-out

505	HTTP Version not supported

Status codes not in the table can be created by the server application. When creating a new status code, the most significant digit should indicate the class of response, as follows:

•	1xx: Informational (request received, continuing process)

•	2xx: Success (request received, understood, and accepted)

•	3xx: Redirection (Further action needed to complete the request)

•	4xx: Client Error (request contains bad syntax or cannot be serviced)

•	5xx: Server Error (server failed to handle a valid request)


TISAPIResponse::Title

TISAPIResponse	See also

Specifies a title for the Content of the HTTP response message.

__property System::AnsiString Title = {read=GetStringVariable, write=SetStringVariable, index=11};

Description

Set the Title property to add a Title header to the HTTP response message. Title is an optional application-specific title associated with the information included in the message.


TISAPIResponse::Version

TISAPIResponse	See also

Specifies the HTTP protocol version that the web client is using.

__property System::AnsiString Version = {read=GetStringVariable, write=SetStringVariable, index=0};

Description

Read Version to ensure that the properties set in the TISAPIResponse object will be understood by the web client. The value of Version is taken from the ProtocolVersion property of the HTTPRequest property.

For more information on the different HTTP protocol versions, see the Internet standards documentation.


TISAPIResponse::WWWAuthenticate

TISAPIResponse	See also

Lists one or more comma-separated challenges when the request fails with StatusCode 401 (Unauthorized).

__property System::AnsiString WWWAuthenticate = {read=GetStringVariable, write=SetStringVariable, index=3};

Description

Set WWWAuthenticate when the HTTP request fails because it requires access to a URI in a realm for which the web client has not provided a password. WWWAuthenticate consists of an authentication scheme name, followed by a comma-separated list of parameter/value pairs that specify the parameters to the authentication scheme. The first parameter/value pair indicates the realm.

For more information about HTTP authentication schemes, see the Internet standards documentation.


TISAPIResponse methods

TISAPIResponse	Alphabetically	Legend

In TISAPIResponse

~TISAPIResponse

GetContent

GetDateVariable

GetIntegerVariable

GetLogMessage

GetStatusCode

GetStringVariable

SendRedirect

SendResponse

SendStream

Sent

SetContent

SetDateVariable

SetIntegerVariable

SetLogMessage

SetStatusCode

SetStringVariable

TISAPIResponse

Derived from TWebResponse

GetCustomHeader

SetCookieField

SetCustomHeader

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TISAPIResponse methods

TISAPIResponse	By object	Legend

~TISAPIResponse

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetContent

GetCustomHeader

GetDateVariable

GetIntegerVariable

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLogMessage

GetStatusCode

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

SendRedirect

SendResponse

SendStream

Sent

SetContent

SetCookieField

SetCustomHeader

SetDateVariable

SetIntegerVariable

SetLogMessage

SetStatusCode

SetStringVariable

TISAPIResponse


TISAPIResponse::TISAPIResponse

TISAPIResponse	See also

Creates an instance of TISAPIResponse to represent the response to the HTTPRequest parameter.

__fastcall TISAPIResponse(Httpapp::TWebRequest* HTTPRequest);

Description

Applications don’t need to call TISAPIResponse to instantiate a ISAPI response object. TISAPIApplication creates a TISAPIResponse for each TISAPIRequest it creates.


TISAPIResponse::GetContent

TISAPIResponse	See also

Reads the value of the Content property.

virtual System::AnsiString __fastcall GetContent();

Description

GetContent is the protected access function for the Content property.


TISAPIResponse::GetDateVariable

TISAPIResponse	See also

Extracts a date from the internal table of HTTP header variables.

virtual System::TDateTime __fastcall GetDateVariable(int Index);

Description

The ISAPI response object uses GetDateVariable to access the properties that represent dates.


TISAPIResponse::GetIntegerVariable

TISAPIResponse	See also

Extracts an integer value from the internal table of HTTP header variables.

virtual int __fastcall GetIntegerVariable(int Index);

Description

The ISAPI response object uses GetIntegerVariable to access the properties that represent integers.


TISAPIResponse::GetLogMessage

TISAPIResponse	See also

Reads the value of the LogMessage property.

virtual System::AnsiString __fastcall GetLogMessage();

Description

GetLogMessage is the protected access function for LogMessage property.


TISAPIResponse::GetStatusCode

TISAPIResponse	See also

Reads the value of the StatusCode property.

virtual int __fastcall GetStatusCode(void);

Description

GetStatusCode is the protected access function for the StatusCode property.


TISAPIResponse::GetStringVariable

TISAPIResponse	See also

Extracts a string value from the internal table of HTTP header variables.

virtual System::AnsiString __fastcall GetStringVariable(int Index);

Description

The ISAPI response object uses GetStringVariable to access the properties that represent strings.


TISAPIResponse::SendRedirect

TISAPIResponse	See also

Sends the response with a StatusCode of 301 (Moved Permanently) and with Location set to the URI parameter.

virtual void __fastcall SendRedirect(const System::AnsiString URI);

Description

Call SendRedirect to redirect the web client request to another URI that is the proper target of the request. SendRedirect does the same thing as setting the StatusCode to 301, the Location to URI, and calling SendResponse.


TISAPIResponse::SendResponse

TISAPIResponse	See also

Sends the ISAPI response message to the web client.

virtual void __fastcall SendResponse(void);

Description

Call SendResponse after setting the properties of the HTTP response object to specify the response that should be made to the web client. If the request should be redirected to another URI, it is more efficient to call SendRedirect.


TISAPIResponse::SendStream

TISAPIResponse	See also

Sends the ISAPI response message with the contents set to the contents of AStream.

virtual void __fastcall SendStream(Classes::TStream* AStream);

Description

Only call SendStream after first calling SendResponse. Unlike SendStream, SendResponse fills the header of the HTTP response message, based on the properties of the TISAPIResponse object. If SendResponse has not been called first to set the header of the HTTP response message, set the ContentStream property to AStream, and call SendResponse.


TISAPIResponse::Sent

TISAPIResponse	See also

Indicates whether the ISAPI response message has been sent.

virtual bool __fastcall Sent(void);

Description

Sent returns true if the SendRedirect or SendStream method has been called. TISAPIApplication objects read Sent to determine whether they should send a response to the web client.


TISAPIResponse::SetContent

TISAPIResponse	See also

Sets the Content property.

virtual void __fastcall SetContent(const System::AnsiString Value);

Description

SetContent is the protected method used by ISAPI response objects to set the Content property.


TISAPIResponse::SetDateVariable

TISAPIResponse	See also

Sets a date-time valued HTTP header property.

virtual void __fastcall SetDateVariable(int Index, const System::TDateTime Value);

Description

SetDateVariable writes date-time to the internal table used to store HTTP header variables. The ISAPI response object uses SetDateVariable to set the properties that represent dates.


TISAPIResponse::SetIntegerVariable

TISAPIResponse	See also

Sets an integer valued HTTP header property.

virtual void __fastcall SetIntegerVariable(int Index, int Value);

Description

SetIntegerVariable writes integer values to the internal table used to store HTTP header variables. The ISAPI response object uses SetIntegerVariable to set the properties that represent integers.


TISAPIResponse::SetLogMessage

TISAPIResponse	See also

Sets the value of the LogMessage property.

virtual void __fastcall SetLogMessage(const System::AnsiString Value);

Description

SetLogMessage is the protected method used by ISAPI response objects to set the LogMessage property.


TISAPIResponse::SetStatusCode

TISAPIResponse	See also

Sets the StatusCode property.

virtual void __fastcall SetStatusCode(int Value);

Description

SetStatusCode is the protected method used by ISAPI response objects to set the StatusCode property.


TISAPIResponse::SetStringVariable

TISAPIResponse	See also

Sets a string valued HTTP header property.

virtual void __fastcall SetStringVariable(int Index, const System::AnsiString Value);

Description

SetStringVariable writes string values to the internal table used to store HTTP header variables. The ISAPI response object uses SetStringVariable to set the properties that represent strings.


Accessibility

Read-only


TISAPIResponse::~TISAPIResponse

TISAPIResponse

~TISAPIResponse frees the memory associated with the TISAPIResponse object.

__fastcall virtual ~TISAPIResponse(void) { }

Description

Do not call ~TISAPIResponse directly. ISAPI response objects are freed by the TISAPIApplication object that creates them.


Scope

Protected


Hierarchy

TObject

TWebResponse


 TLabel

Hierarchy	Properties	Methods	Events	See also

TLabel is a nonwindowed control that displays text on a form. This text can be used to label another control, and can set focus to that control when the user types an accelerator key.

Unit

stdctrls

Description

TLabel is not a descendant of TWinControl, so it does not have its own window and can’t receive direct input from the keyboard. To add an object to a form that can respond to keyboard input (other than setting focus to another object when an accelerator key is typed) in addition to displaying text, use TStaticText.

To add an object to a form that displays text that a user can scroll or edit, use TEdit.


TLabel properties

TLabel	Alphabetically	Legend

Derived from TCustomLabel

Alignment

AutoSize

FocusControl

Layout

ShowAccelChar

Transparent

WordWrap

Derived from TGraphicControl

Canvas

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TLabel properties

TLabel	By object	Legend

Align

Alignment

AutoSize

BoundsRect

Canvas

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

FocusControl

Font

Height

Hint

Layout

Left

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowAccelChar

ShowHint

Tag

Top

Transparent

VCLComObject

Visible

Width

WindowProc

WordWrap


TLabel events

TLabel	Alphabetically	Legend

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TLabel events

TLabel	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TLabel methods

TLabel	Alphabetically

In TLabel

~TLabel

TLabel

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TLabel methods

TLabel	By object

~TLabel

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TLabel

Update


TLabel::TLabel

TLabel

Creates a new TLabel object.

__fastcall virtual TLabel(Classes::TComponent* AOwner) : Stdctrls::TCustomLabel(AOwner) { }

Description

Call TLabel indirectly, using the new keyword, to create a label at runtime.


TLabel::~TLabel

TLabel

Frees the memory associated with the TLabel object.

__fastcall virtual ~TLabel(void) { }

Description

Do not call ~TLabel directly. Instead, use the delete keyword on the object, which causes ~TLabel to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl

TCustomLabel


TList

Hierarchy	Properties	Methods	See also

TList maintains a list of pointers to objects.

Unit

classes

Description

Use a TList object to store and maintain a list of objects. TList introduces properties and methods to

•	Add or delete the objects in the list.

•	Rearrange the objects in the list.

•	Locate and access objects in the list.

•	Sort the objects in the list.


TList properties

TList	Alphabetically	Legend

In TList

Capacity

Count

Items

List


TList properties

TList	By object	Legend

Capacity

Count

Items

List


TList::Capacity

TList	See also

Specifies the allocated size of the array of pointers maintained by the TList object.

__property int Capacity = {read=FCapacity, write=SetCapacity, nodefault};

Description

Set Capacity to the number of pointers the list will need to contain. When setting the Capacity property, an EOutOfMemory exception occurs if there is not enough memory to expand the list to its new size.

Read Capacity to learn number of objects the list can hold without reallocating memory. Don’t confuse Capacity with the Count property, which is the number of entries in the list that are in use. The value of Capacity is always greater than or equal to the value of Count. When Capacity is greater than Count, the unused memory can be reclaimed by setting Capacity to Count.

When an object is added to a list that is already filled to capacity, the Capacity property is automatically increased. Setting Capacity before adding objects can reduce the number of memory reallocations and thereby improve performance. For example,

List->Clear();

List->Capacity = Count;

for (int I = 0; I < Count; I++)

  List->Add(...);

The assignment to Capacity before the for loop ensures that each of the following Add operations doesn't cause the list to be reallocated. Avoiding reallocations on the calls to Add improves performance and ensures that the Add operations never throw an exception.


TList::Count

TList	See also 	Example

Indicates the number of entries in the list that are in use.

__property int Count = {read=FCount, write=SetCount, nodefault};

Description

Read Count to determine the number of entries in the Items array.

Increasing the size of Count will add the necessary number of NULL pointers to the end of the Items array. Decreasing the size of Count will remove the necessary number of entries from the end of the Items array.

Count is not always the same as the number of objects referenced in the list. Some of the entries in the Items array may contain NULL pointers. To remove the NULL pointers and set Count to the number of entries that contain references to objects, call the Pack method.


TList::Items

TList	See also 	Example

Lists the object references.

__property void * Items[int Index] = {read=Get, write=Put};

Description

Use Items to obtain a pointer to a specific object in the array. The Index parameter indicates the index of the object, where 0 is the index of the first object, 1 is the index of the second object, and so on. Set Items to change the reference at a specific location.

Use Items with the Count property to iterate through all of the objects in the list.

Not all of the entries in the Items array need to contain references to objects. Some of the entries may be NULL pointers. To remove the NULL pointers and reduce the size of the Items array to the number of objects, call the Pack method.


TList::List

TList	See also

Specifies the array of pointers that make up the Items array.

typedef void *TPointerList[134217727];

typedef TPointerList *PPointerList;

__property PPointerList List = {read=FList};

Description

Use List to gain direct access to the Items array.


TList methods

TList	Alphabetically

In TList

~TList

Add

Clear

Delete

Error

Exchange

Expand

First

IndexOf

Insert

Last

Move

Pack

Remove

Sort

TList

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TList methods

TList	By object

~TList

Add

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

Error

Exchange

Expand

FieldAddress

First

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

IndexOf

InheritsFrom

InitInstance

Insert

InstanceSize

Last

MethodAddress

MethodName

Move

NewInstance

Pack

Remove

SafeCallException

Sort

TList


TList.Add

TList	See also 	Example

Inserts a new item to the end of a list.

int __fastcall Add(void * Item);

Description

Call Add to insert a new object at the end of the Items array. Add returns the index of the new item, where the first item in the list has an index of 0.

Add allocates more memory if the Items array already uses up the Capacity of the list object. Add increases the value of Count to reflect the addition of a new pointer.

Note:	Add always inserts the Item pointer at the end of the Items array, even if the Items array contains NULL pointers.


TList::Clear

TList	See also

Deletes all items from the list.

DYNAMIC void __fastcall Clear(void);

Description

Call Clear to empty the Items array and set the Count to 0. Clear also frees the memory used to store the Items array and sets the Capacity to 0.


TList::Delete

TList	See also

Removes the item at the position given by the Index parameter.

void __fastcall Delete(int Index);

Description

Call Delete to remove the item at a specific position from the list. The index is zero-based, so the first item has an Index value of 0, the second item has an Index value of 1, and so on. Calling Delete moves up all items in the Items array that follow the deleted item, and reduces the Count.

To remove the reference to an item without deleting the entry from the Items array and changing the Count, set the Items property for Index to NULL.

Note:	Delete does not free up any memory associated with the item. To free the memory that was used to store a deleted item, set the Capacity property.


TList::~TList

TList	See also

Destroys an instance of TList.

__fastcall virtual ~TList(void);

Description

Do not call ~TList directly in an application. Instead, use the delete keyword.

~TList frees the memory used to store the list of items.

Note:	~TList does not free the memory pointed to by the elements of the list.


TList::Error

TList	See also

Throws an EListError exception.

virtual void __fastcall Error(const System::AnsiString Msg, int Data) { Error(__classid(TList), Msg, Data);

Description

Call Error to throw an exception when an error occurs working with a TList object. Error assembles an error message from the format string passed as the Msg parameter and the data value passed as the Data parameter, and then throws an EListError exception.

Call Error rather than adding a line such as

throw EListError(MyMsg, iBadValue);

to reduce the code size of an application.


TList::Exchange

TList	See also

Swaps the position of two items in the Items array.

void __fastcall Exchange(int Index1, int Index2);

Description

Call Exchange to swap the positions of the items at positions Index1 and Index2 of the Items array. The indexes are zero-based, so the first item in the list has an index value of 0, the second item has an index value of 1, and so on.


TList::Expand

TList	See also

Increases the Capacity of the list.

TList* __fastcall Expand(void);

Description

Call Expand to create more space for adding new items to the list. Expand does nothing if the list is not already filled to Capacity.

If Count = Capacity, Expand increases the Capacity of the list as follows. If the value of Capacity is greater than 8, Expand increases the Capacity of the list by 16. If the value of Capacity is greater than 4, but less than 9, the Capacity of the list increases by 8. If the value of Capacity is less than 4, the Capacity of the list grows by 4.

The returned value is the expanded list object.


TList::First

TList	See also

Returns Items[0].

void * __fastcall First(void);

Description

Call First to get the first pointer in the Items array.


TList::IndexOf

TList	See also 	Example

Returns the index of the first entry in the Items array with a specified value.

int __fastcall IndexOf(void * Item);

Description

Call IndexOf to get the index for a pointer in the Items array. Specify the pointer as the Item parameter.

The first item in the array has index 0, the second item has index 1, and so on. If an item is not in the list, IndexOf returns -1. If a pointer appears more than once in the array, IndexOf returns the index of the first appearance.


TList::Insert

TList	See also

Adds an object to the Items array at the position specified by Index.

void __fastcall Insert(int Index, void * Item);

Description

Call Insert to add Item to the middle of the Items array. The Index parameter is a zero-based index, so the first position in the array has an index of 0. Insert adds the item at the indicated position, shifting the item that previously occupied that position, and all subsequent items, up. Insert expands the Capacity of the list if necessary, and increases the Count property.

To replace a NULL pointer in the array with a new item, without growing the Items array, set the Items property.


TList::Last

TList	See also 	Example

Returns Items[Count - 1].

void * __fastcall Last(void);

Description

Call Last to retrieve the last pointer in the Items array.


TList::Move

TList	See also

Changes the position of an item in the Items array.

void __fastcall Move(int CurIndex, int NewIndex);

Description

Call Move to move the item at the position CurIndex so that it occupies the position NewIndex. CurIndex and NewIndex are zero-base indexes into the Items array.


TList::Pack

TList	See also 	Example

Deletes all NULL items from the Items array.

void __fastcall Pack(void);

Description

Call Pack to move all non-NULL items to the front of the Items array and reduce the Count property to the number of items actually used. Pack does not free up the memory used to store the NULL pointers. To free up the memory for the unused entries removed by Pack, set the Capacity property to the new value of Count.


TList::Remove

TList	See also 	Example

Deletes the first reference to the Item parameter from the Items array.

int __fastcall Remove(void * Item);

Description

Call Remove to remove a specific item from the Items array when its index is unknown. The value returned is the index of the item in the Items array before it was removed. After an item is removed, all of the items that follow it are moved up in index position and the Count is reduced by one.

If the Items array contains more than one copy of the pointer, only the first copy is deleted.


TList::Sort

TList	See also

Performs a QuickSort on the list based on the comparison function Compare.

typedef int __fastcall (*TListSortCompare)(void * Item1, void * Item2);

void __fastcall Sort(TListSortCompare Compare);

Description

Call Sort to sort the items in the Items array. Compare is a comparison function that indicates how the items are to be ordered. Compare returns < 0 if Item1 is less and Item2, 0 if they are equal and > 0 if Item1 is greater than Item2.


TList::TList

TList

Creates a new TList object.

__fastcall virtual ~TList(void);

Description

Do not call TList directly. Instead, use the new keyword.


Accessibility

Read-only


Hierarchy

TObject


 TListBox

Hierarchy	Properties	Methods	Events

TListBox is a wrapper for a Windows list box control.

Unit

stdctrls

Description

TListBox implements the generic behavior introduced in TCustomListbox. TListBox publishes many of the properties parent class's from TCustomListBox, but does not introduce any new behavior.

Use TListBox to display a scrollable list of items that users can select, add, or delete. For specialized list boxes, use other descendant classes of TCustomListBox or derive from it.


TListBox properties

TListBox	Alphabetically	Legend

Derived from TCustomListBox

BorderStyle

Canvas

Columns

ExtendedSelect

IntegralHeight

ItemHeight

ItemIndex

Items

MultiSelect

SelCount

Selected

Sorted

Style

TabWidth

TopIndex

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TListBox properties

TListBox	By object	Legend

Align

BorderStyle

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

ExtendedSelect

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IntegralHeight

ItemHeight

ItemIndex

Items

Left

MultiSelect

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

SelCount

Selected

ShowHint

Showing

Sorted

Style

TabOrder

TabStop

TabWidth

Tag

Top

TopIndex

VCLComObject

Visible

Width

WindowProc


TListBox events

TListBox	Alphabetically	Legend

Derived from TCustomListBox

OnDrawItem

OnMeasureItem

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TListBox events

TListBox	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDrawItem

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMeasureItem

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TListBox methods

TListBox	Alphabetically

In TListBox

~TListBox

TListBox

Derived from TCustomListBox

Clear

ItemAtPos

ItemRect

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TListBox methods

TListBox	By object

~TListBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

ItemAtPos

ItemRect

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TListBox

Update

UpdateControlState


TListBox::TListBox

TListBox	See also

Creates a new TListBox object.

__fastcall virtual TListBox(Classes::TComponent* AOwner) : Stdctrls::TCustomListBox(AOwner) { }

__fastcall TListBox(HWND ParentWindow) : Stdctrls::TCustomListBox(ParentWindow) { }

Description

Call TListBox indirectly, using the new keyword, to create a list box at runtime.

Pass a single Component as a parameter to provide the TListBox object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the list box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TListBox::~TListBox

TListBox

Frees the memory associated with the TListBox object.

__fastcall virtual ~TListBox(void) { }

Description

Do not call ~TListBox directly. Instead, use the delete keyword on the object, which causes ~TListBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomListBox


TListItem

Hierarchy	Properties	Methods	See also

TListItem is an individual item of a TListView control.

Unit

comctrls

Description

Use TListItem to specify the appearance and data associations of an item in a list view. All the list items of the list view are collected by a TListItems object to make up the Items property of the TListView control.


TListItem properties

TListItem	Alphabetically	Legend

In TListItem

Caption

Checked

Cut

Data

DropTarget

Focused

Handle

ImageIndex

Index

Left

ListView

OverlayIndex

Owner

Selected

StateIndex

SubItems

Top


TListItem properties

TListItem	By object	Legend

Caption

Checked

Cut

Data

DropTarget

Focused

Handle

ImageIndex

Index

Left

ListView

OverlayIndex

Owner

Selected

StateIndex

SubItems

Top


TListItem::Caption

TListItem	See also 	Example

Specifies the text that labels the item in the list.

__property System::AnsiString Caption = {read=FCaption, write=SetCaption};

Description

Use Caption to name the list item. The Caption appears with an associated image that depends on the ViewStyle property of the list view.

If the ReadOnly property of the list view is false, the user is allowed to edit the caption.


TListItem::Checked

TListItem	See also

Determines whether a check mark appears next to the list item.

__property bool Checked = {read=GetChecked, write=SetChecked, nodefault};

Description

Use Checked to indicate whether the list item represents a selected option by displaying a check mark next to the item in the list view. When Checked is true, a check mark appears next to the item. When Checked is false, no check mark appears.

Note:	Set the CheckBoxes property of the ListView to true before using the Checked property.


TListItem.Cut
TListItem::Cut

TListItem	See also

Determines whether the list item is drawn as if it is selected for a cut operation.

__property bool Cut = {read=GetState, write=SetState, index=0, nodefault};

Description

Set the Cut property to give the list item the grayed-out appearance of an item selected for cutting in the Windows Explorer. Cut does not copy the item to the Clipboard or remove it from the list: the application must still perform these operations.


TListItem::Data

TListItem	See also

Specifies any application-specific data associated with the list item.

__property void * Data = {read=FData, write=SetData};

Description

Use Data to associate arbitrary data structure with the list item. When the user selects or deletes the list item, Data allows the application to quickly access information about the meaning of the list item to implement the appropriate response.


TListItem::DropTarget

TListItem	See also

Determines whether the list item appears selected as a drag and drop target.

__property bool DropTarget = {read=GetState, write=SetState, index=1, nodefault};

Description

Use DropTarget to display the list item as the current drop target of the object the user is dragging. Setting DropTarget to true sets the DropTarget property of all other items in the list view to false.


TListItem::Focused

TListItem	See also

Indicates whether the list item has input focus.

__property bool Focused = {read=GetState, write=SetState, index=2, nodefault};

Description

Set Focused to true to allow the user to edit the Caption.

Note:	Only one item in the tree view should have focus at a time.  When setting Focused to true, be sure to set the Focused property of all other items in the list view to false. When the list item is Focused, it appears surrounded by a standard focus rectangle.


TListItem::Handle

TListItem	See also

Specifies the window handle of the list view that owns the list item.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Use Handle as a parameter in Windows API function calls that require the handle to the list view window.


TListItem::ImageIndex

TListItem	See also 	Example

Determines which image is displayed as the icon for the list item.

__property int ImageIndex = {read=FImageIndex, write=SetImage, index=0, nodefault};

Description

Set ImageIndex to associate the list item with one of the images in the LargeImages or SmallImages property of the list view. If the ViewStyle of the list view is vsIcon, ImageIndex is the index of the image in the LargeImages property of the list view, where 0 specifies the first image. If the ViewStyle of the list view is vsSmallIcon, vsList, or vsReport, ImageIndex is the index of the image in the SmallImages property of the list view.


TListItem::Index

TListItem	See also 	Example

Indicates the position of the list item in the TListItems collection.

__property bool Cut = {read=GetState, write=SetState, index=0, nodefault};

Description

Use Index to locate the item in the list view. The first item has an index of 0, the second item has an index of 1, and so on.


TListItem::Left

TListItem	See also

Specifies the distance, in pixels, from the left edge of the list view to the left edge of the list item.

__property int Left = {read=GetLeft, write=SetLeft, nodefault};

Description

Use Left to horizontally position the list item within the list view. Only use the Left property when the ViewStyle property of the list view is vsIcon or vsSmallIcon.


TListItem::ListView

TListItem	See also

Indicates the list view control that displays the list item.

__property TCustomListView* ListView = {read=GetListView};

Description

Read ListView to access the list view object that displays the item. Use the properties and methods of the list view object to make changes that affect the list item or to manipulate other items in the list.

Do not confuse the ListView that displays the item with the Owner of the item. The Owner is the TListItems object that manages the collection of all list items. The list view is the Owner of that TListItems object.


TListItem::OverlayIndex

TListItem	See also

Determines which image from the image list is used as an overlay mask.

__property int OverlayIndex = {read=FOverlayIndex, write=SetImage, index=1, nodefault};

Description

Use OverlayIndex to display an overlay mask on an item in the list when the ViewStyle of the list view is vsIcon or vsSmallIcon. OverlayIndex is the index of the overlay image in the StateImages property of the list view.

An overlay mask is an image drawn transparently over the icon for the item in the list view. For example, to indicate that an item is no longer available, an application could use an overlay image of an X over the item's image.


TListItem::Owner

TListItem	See also

Specifies the TListItems object that owns the list item.

__property TListItems* Owner = {read=FOwner};

Description

Use Owner to access the TListItems object that manages all the list items for the list view. Use the methods of the Owner object to temporarily prevent updates to the image of the list item while it is changed or to add or delete list items.

Do not confuse the Owner property with the list view control that displays the item. The ListView property specifies the list view control that owns the TListItems object.


TListItem::Selected

TListItem	See also

Indicates whether the list item is selected.

__property bool Selected = {read=GetState, write=SetState, index=3, nodefault};

Description

Use Selected to select or unselect the list item. If the MultiSelect property of the list view is false, setting Selected to true sets the Selected property of all other list items in the list view to false. The appearance of a selected item depends on whether it has focus and whether the system colors are used for selection.


TListItem::StateIndex

TListItem	See also

Specifies which image from the StateImages image list to display for the item.

__property int StateIndex = {read=FStateIndex, write=SetImage, index=2, nodefault};

Description

Set StateIndex to associate the list item with one of the images in the StateImages property of the list view, where 0 specifies the first image. Change StateIndex to display a different image when the state of the item changes.

The state image appears to the left of the normal list item.


TListItem::SubItems

TListItem	See also 	Example

Contains any strings that appear as subitems to the list item.

__property Classes::TStrings* SubItems = {read=FSubItems, write=SetSubItems};

Description

Use SubItems to add strings that appear in the additional columns to the right of the list view item when the list view’s ViewStyle property is vsReport. The TStrings object that implements the SubItems property is created when the list item is created. To the methods of the SubItems object to add or delete subitems.

Note:	Subitems are only visible when the list view's ViewStyle property is set to vsReport.


TListItem.Top
TListItem::Top

TListItem	See also

Specifies the distance, in pixels, from the top of the list view to the top of the list item.

__property int Top = {read=GetTop, write=SetTop, nodefault};

Description

Use Top to vertically position the list item within the list view. Only use the Top property when the ViewStyle property of the list view is vsIcon or vsSmallIcon.


TListItem methods

TListItem	Alphabetically

In TListItem

~TListItem

CancelEdit

Delete

DisplayRect

EditCaption

GetPosition

MakeVisible

SetPosition

TListItem

Update

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TListItem methods

TListItem	By object

~TListItem

CancelEdit

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Delete

Dispatch

DisplayRect

EditCaption

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetPosition

InheritsFrom

InitInstance

InstanceSize

MakeVisible

MethodAddress

MethodName

NewInstance

SafeCallException

SetPosition

TListItem

Update


TListItem::CancelEdit

TListItem	See also

Cancels the editing of the list item's caption.

void __fastcall CancelEdit(void);

Description

Call CancelEdit to end the editing of the item’s caption, discarding any changes made by the user.


TListItem::TListItem

TListItem	See also

Creates an instance of TListItem.

__fastcall TListItem(TListItems* AOwner);

Description

Call TListItem indirectly using the new keyword to instantiate a TListItem object at runtime. List items added to the list view at design time are created automatically. At runtime, use the Add method of the TListItems object to create a list item and add it to the list view.


TListItem::Delete

TListItem	See also

Deletes the list item from its list view.

void __fastcall Delete(void);

Description

Use the Delete method to delete a list item. Delete removes the item from the image of the list view.


TListItem::~TListItem

TListItem	See also

Destroys an instance of TListItem.

__fastcall virtual ~TListItem(void);

Description

Do not call ~TListItem directly. Instead, use delete, which removes the item from the list view windows before freeing the associated memory.


TListItem::DisplayRect

TListItem	See also

Returns the bounding rectangle of the list item.

Windows::TRect __fastcall DisplayRect(TDisplayCode Code);

Description

Use DisplayRect to get the display coordinates of the list item. The Code parameter specifies what part of the item the bounding rectangle surrounds. These are the possible values for the Code parameter.

Value	Meaning

drBounds	Returns the bounding rectangle of the entire list item, including the icon and label.

drIcon	Returns the bounding rectangle of the icon or small icon.

drLabel	Returns the bounding rectangle of the item text.

drSelectBounds	Returns the union of the icon and label rectangles, but excludes columns in report view.


TListItem::EditCaption

TListItem	See also

Begins in-place editing of the list item's caption.

bool __fastcall EditCaption(void);

Description

Call EditCaption to put the list item into edit mode. Before bringing up the in-place editor for the item’s caption, EditCaption makes the item the only selected item in the list view and gives it input focus.


TListItem::GetPosition

TListItem	See also

Returns the position of the list item as a point.

tagPOINT __fastcall GetPosition();

Description

Call GetPosition to obtain the upper left coordinate of the list item. GetPosition returns a point with the x coordinate set to the value of Left and the y coordinate set to the value of Top.


TListItem::MakeVisible

TListItem	See also

Scrolls the list view, if necessary, to ensure a list item is in view.

void __fastcall MakeVisible(bool PartialOK);

Description

Call MakeVisible to ensure that the user can see the list item in the list view. The PartialOK parameter specifies whether the item must be entirely visible. If PartialOK is true, no scrolling occurs if the item is at least partially visible. If PartialOK is false, MakeVisible ensures that the entire list item is visible in the list view.


TListItem::SetPosition

TListItem	See also

Positions the list item in its list view control.

void __fastcall SetPosition(const tagPOINT &Value);

Description

Call SetPosition to move the list item to a specified position. The Value parameter specifies the desired coordinates of the upper left corner of the list item.

Note:	The list view control must have its ViewStyle property set to either vsIcon or vsSmallIcon.


TListItem::Update

TListItem	See also

Updates the image of the list item in the list view display.

void __fastcall Update(void);

Description

Call Update to update the image of the list view to reflect any changes made to the list item. Changing the Caption, position, or state of the list item automatically updates the list item’s image.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


 TListView

Hierarchy	Properties	Methods	Events	See also

TListView displays a list of items in various ways.

Unit

comctrls

Description

Use TListView to manage and display a list of items in a form. The items can be displayed in columns with column headers and sub-items, or vertically or horizontally, with small or large icons.

TListView publishes many of the properties, events, and methods of TCustomListView, but does not introduce any new behavior.


TListView properties

TListView	Alphabetically	Legend

Derived from TCustomListView

AllocBy

BorderStyle

BoundingRect

Checkboxes

Column

ColumnClick

Columns

DropTarget

GridLines

HideSelection

HotTrack

IconOptions

ItemFocused

Items

LargeImages

MultiSelect

ReadOnly

RowSelect

SelCount

Selected

ShowColumnHeaders

SmallImages

SortType

StateImages

TopItem

ViewOrigin

ViewStyle

VisibleRowCount

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TListView properties

TListView	By object	Legend

Align

AllocBy

BorderStyle

BoundingRect

BoundsRect

Brush

Checkboxes

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Column

ColumnClick

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

DropTarget

Enabled

Font

GridLines

Handle

Height

HelpContext

HideSelection

Hint

HotTrack

IconOptions

ItemFocused

Items

LargeImages

Left

MultiSelect

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

RowSelect

SelCount

Selected

ShowColumnHeaders

ShowHint

Showing

SmallImages

SortType

StateImages

TabOrder

TabStop

Tag

Top

TopItem

VCLComObject

ViewOrigin

ViewStyle

Visible

VisibleRowCount

Width

WindowProc


TListView events

TListView	Alphabetically	Legend

Derived from TCustomListView

OnChange

OnChanging

OnColumnClick

OnCompare

OnDeletion

OnEdited

OnEditing

OnInsert

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TListView events

TListView	By object	Legend

OnChange

OnChanging

OnClick

OnColumnClick

OnCompare

OnDblClick

OnDeletion

OnDragDrop

OnDragOver

OnEdited

OnEditing

OnEndDrag

OnEnter

OnExit

OnInsert

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TListView methods

TListView	Alphabetically

In TListView

~TListView

TListView

Derived from TCustomListView

AlphaSort

Arrange

CustomSort

FindCaption

FindData

GetItemAt

GetNearestItem

GetNextItem

GetSearchString

IsEditing

Scroll

StringWidth

UpdateItems

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TListView methods

TListView	By object

~TListView

AlphaSort

Arrange

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CustomSort

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindCaption

FindComponent

FindData

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetItemAt

GetNamePath

GetNearestItem

GetNextItem

GetParentComponent

GetSearchString

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

IsEditing

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

Scroll

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

StringWidth

TListView

Update

UpdateControlState

UpdateItems


TListView::TListView

TListView	See also

Creates a new TListView object.

__fastcall virtual TListView(Classes::TComponent* AOwner) : Comctrls::TCustomListView(AOwner) { }

__fastcall TListView(HWND ParentWindow) : Comctrls::TCustomListView(ParentWindow) { }

Description

Call TListView indirectly, using the new keyword, to create a list view object at runtime.

Pass a single component as a parameter to provide the TListView object with an owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the list view in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TListView::~TListView

TListView

Frees the memory associated with the TListView object.

__fastcall virtual ~TListView(void) { }

Description

Do not call ~TListView directly. Instead, use the delete keyword on the object, which causes ~TListView to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomListView


TLookupList

Hierarchy	Methods	See also

TLookupList maintains a list of lookup values associated with a set of key field values.

Unit

db

Description

TLookupList is used by TField to implement a cache of lookup values. Each value in the lookup list is associated with a set of values on the key fields in the lookup data set. Lookup fields match the values of the fields identified by their KeyFields property with the values of the key fields from the lookup data set. When these values match, the value of the lookup field is set to the associated value from TLookupList.

Use TLookupList to generate a lookup list programmatically when there is no actual lookup dataset. Set the LookupList property of the lookup field to a programmatically created TLookupList object and set the LookupCache property of the field to true. If the other lookup properties of the field are not set, the field will use the supplied lookup list without overwriting it with values from a lookup dataset.


TLookupList methods

TLookupList	Alphabetically

In TLookupList

~TLookupList

Add

Clear

TLookupList

ValueOfKey

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TLookupList methods

TLookupList	By object

~TLookupList

Add

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TLookupList

ValueOfKey


TLookupList.Add

TLookupList	See also

Adds a lookup value to the list for a given key value.

void __fastcall Add(const System::Variant &AKey, const System::Variant &AValue);

Description

Lookup fields call Add when building the lookup cache to associate lookup values with the values of the key fields in the lookup dataset. The AKey parameter is a variant or variant array that represents the value or values of the key fields. AValue is a variant that represents the value of the lookup field associated with the key field values.

Use Add to build a lookup list from scratch when there is no actual lookup dataset.


TLookupList::Clear

TLookupList	See also

Empties the lookup list and frees the associated memory.

void __fastcall Clear(void);

Description

Call Clear to empty the current values in the lookup list when building a lookup list programmatically. Lookup fields call Clear automatically before regenerating the lookup cache if the list represents the values in a lookup dataset.


TLookupList::TLookupList

TLookupList	See also

Creates an instance of TLookupList.

__fastcall TLookupList(void);

Description

Applications should not need to call TLookupList. Instances of TLookupList are created by the lookup field that uses the list for its lookup cache. To obtain one of these instances, read the LookupList property of the field.

TLookupList allocates the helper objects it uses to maintain the list of lookup values.


TLookupList::~TLookupList

TLookupList	See also

Destroys an instance of TLookupList.

__fastcall virtual ~TLookupList(void);

Description

Do not call ~TLookupList directly in an application. The lookup field that uses TLookupList destroys the lookup list when it is done.

~TLookupList frees all memory used to store the list of lookup values.


TLookupList::ValueOfKey

TLookupList	See also

Returns the lookup value associated with a set of key field values.

System::Variant __fastcall ValueOfKey(const System::Variant &AKey);

Description

Call ValueOfKey to look up the value for a lookup field that has the set of values specified by the AKey parameter on the fields identified by its KeyFields property. AKey is a variant or variant array that contains the values on the key fields in the lookup data set that uniquely specify a lookup field value.


Hierarchy

TObject


ELowCapacityError

Hierarchy	Properties	Methods	See also

ELowCapacityError is the exception class for when an attempt is made to allocate more memory than is available for the decision cube.

Unit

mxarrays

Description

ELowCapacityError is thrown when the cache of a decision cube is too big. The memory available to the decision cube can be increased by changing the Capacity property of the decision cube or the memory demands of the decision cube can be reduced by deactivating some of the cube dimensions.


ELowCapacityError properties

ELowCapacityError	Alphabetically

Derived from Exception

HelpContext

Message


ELowCapacityError properties

ELowCapacityError	By object

HelpContext

Message


ELowCapacityError methods

ELowCapacityError	Alphabetically

In ELowCapacityError

~ELowCapacityError

ELowCapacityError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ELowCapacityError methods

ELowCapacityError	By object

~ELowCapacityError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ELowCapacityError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


ELowCapacityError::ELowCapacityError

ELowCapacityError	See also

ELowCapacityError creates a new ELowCapacityError object.

__fastcall ELowCapacityError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall ELowCapacityError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall ELowCapacityError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall ELowCapacityError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall ELowCapacityError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall ELowCapacityError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall ELowCapacityError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall ELowCapacityError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

ELowCapacityError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw ELowCapacityError("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


ELowCapacityError::~ELowCapacityError

ELowCapacityError	See also

~ELowCapacityError frees the memory associated with the ELowCapacityError object.

__fastcall virtual ~ELowCapacityError(void) { }

Description

Do not call ~ELowCapacityError directly. Instead, use the delete keyword on the object, which causes ~ELowCapacityError to be invoked automatically.


Hierarchy

TObject

Exception


ELowCapacityError example

ELowCapacityError


TListColumn

Hierarchy	Properties	Methods	See also

TListColumn represents a column in a report-style list view.

Unit

comctrls

Description

TListView objects use TListColumns to maintain a collection of TListColumn objects.


TListColumn properties

TListColumn	Alphabetically	Legend

In TListColumn

Alignment

Caption

DisplayName

Width

WidthType

Derived from TCollectionItem

Collection

ID

Index


TListColumn properties

TListColumn	By object	Legend

Alignment

Caption

Collection

DisplayName

ID

Index

Width

WidthType


TListColumn::Alignment

TListColumn	See also

Specifies how all text is aligned within the list column.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

Use Alignment to specify the horizontal placement of text in the column. The text includes the Caption that appears at the top of the column and the text labels of individual list items that appear in the column. These are the possible values of Alignment:

Value	Meaning

taLeftJustify	Align text on the left side of the header.

taCenter	Center text in the column.

taRightJustify	Align text on the right side of the header.


TListColumn::Caption

TListColumn	See also 	Example

Specifies the text that appears at the top of the column.

__property System::AnsiString Caption = {read=FCaption, write=SetCaption};

Description

Use Caption to label the type of item that appears in the column. If the list-view control’s ViewStyle and ShowColumnHeaders properties are set to vsReport and true, respectively, the value of Caption appears at the top of the column.


TListColumn::DisplayName

TListColumn	See also

DisplayName is a string that names an individual list view column within a collection of columns.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

Use DisplayName to specify the name of the column as it should appear in the columns editor at design time. If the Caption property is set, the value of DisplayName is the same as Caption. Otherwise, DisplayName is the name of the list column class.


TListColumn::Width

TListColumn	See also

Specifies the width of the column.

typedef int TWidth;

__property TWidth Width = {read=GetWidth, write=SetWidth, default=50};

Description

Use Width to specify the width of the list column, in pixels. If Width is assigned the value -1, the list column is automatically resized to accommodate the text in the column. If Width is assigned the value -2, the list column is automatically resized to accommodate the column header (that is, the text in the Caption property). For more readable code, use the global ColumnTextWidth and ColumnHeaderWidth constants when assigning negative values to Width:

Constant	Value	Meaning

ColumnTextWidth	-1	Column is resized to fit text of items.

ColumnHeaderWidth	-2	Column is resized to fit header only.

For example, the following statement causes the leftmost column of ListView1 to be resized automatically to accommodate its text:

ListView1->Columns->Items[0]->Width = ColumnTextWidth;

In the form designer, the same thing can be accomplished by opening the Columns editor for ListView1, selecting the first list column, and typing -1 next to Width in the Object Inspector.

When a column is automatically resized, the value of Width changes to indicate the actual column width. The read-only WidthType property, however, retains its value of -1 or -2.


TListColumn::WidthType

TListColumn	See also

Indicates whether the column is sized automatically.

typedef int TWidth;

__property TWidth WidthType = {read=FWidth, nodefault};

Description

The read-only WidthType property indicates how the column width is determined. WidthType is set to the same value as Width. WidthType, however, retains its negative value when Width changes automatically.

If WidthType returns -1, the list column is automatically resized to accommodate the text in the column. If WidthType returns -2, the list column is automatically resized to accommodate the column header. If WidthType returns a nonnegative value, the column is not resized automatically; in this case, the value of Width and WidthType should be the same.

To enable automatic column resizing, assign the value -1 or -2 directly to Width.


TListColumn methods

TListColumn	Alphabetically

In TListColumn

~TListColumn

Assign

TListColumn

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TListColumn methods

TListColumn	By object

~TListColumn

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TListColumn


TListColumn::Assign

TListColumn	See also

Copies the properties of the source list-column.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to copy the display attributes of another list column. Assign sets the Alignment, Width, and Caption values to match the source object. If the Source parameter is not a list column, Assign calls the inherited method to allow assignment from any object that can copy to a list column in its AssignTo method.


TListColumn::TListColumn

TListColumn	See also

Creates and initializes a list column.

__fastcall virtual TListColumn(Classes::TCollection* Collection);

Description

Do not call TListColumn directly. Instead, use the keyword new, which returns an indirect reference to the new list column. TListColumn objects placed on a form at design time are created automatically.

The Collection parameter specifies the TListColumns object that represents the list columns for the list view that uses this column. Columns added to list view objects at design time are created automatically. At runtime, create list columns indirectly using the Add method of the TListColumns object.

TListColumn initializes the Alignment property to taLeftJustify and the Width property to 50.


TListColumn::~TListColumn

TListColumn 	See also

Destroys the list column and frees its memory.

__fastcall virtual ~TListColumn(void);

Description

Do not call ~TListColumn directly. Instead, use the delete keyword on the object, which causes ~TListColumn to be invoked automatically.

~TListColumn eliminates the TListColumn instance and, if necessary, deletes the column from the list-view control.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


TListColumns

Hierarchy	Properties	Methods	See also

TListColumns is a collection of TListColumn objects.

Unit

comctrls

Description

Each TListColumns represents a collection of TListColumn objects in a TListView. At design time, use the list-view control’s Columns editor to add, remove, or modify columns.


TListColumns properties

TListColumns	Alphabetically	Legend

In TListColumns

Items

Owner

Derived from TCollection

Count

ItemClass


TListColumns properties

TListColumns	By object	Legend

Count

ItemClass

Items

Owner


TListColumns::Items

TListColumns	See also

Lists the columns in the collection.

__property TListColumn* Items[int Index] = {read=GetItem, write=SetItem};

Description

Use Items to directly access the list column objects in the collection. The value of the Index parameter corresponds to the Index property of TListColumn. It represents the position of the column in the list view.


TListColumns::Owner

TListColumns	See also

Specifies the list-view control to which the TListColumns instance belongs.

__property TCustomListView* Owner = {read=FOwner};

Description

The read-only Owner property indicates which list-view control uses the TListColumns object to implement its Columns property.


TListColumns methods

TListColumns	Alphabetically

In TListColumns

~TListColumns

Add

TListColumns

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TListColumns methods

TListColumns	By object

~TListColumns

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TListColumns


TListColumns.Add

TListColumns	See also 	Example

Creates a new TListColumn instance and adds it to the Items array.

HIDESBASE TListColumn* __fastcall Add(void);

Description

Call Add to add a new list column to the end of the items array. Add returns the new list column. At design time, use the list-view control’s Columns editor to add columns to the list view.


TListColumns::TListColumns

TListColumns	See also

Creates and initializes a TListColumns object.

__fastcall TListColumns(TCustomListView* AOwner);

Description

Do not call TListColumns directly. Instances of TListView create the TListColumns object from their own constructors. If it is necessary to create a TListColumns object explicitly, use the keyword new, which returns an indirect reference to the new object.

The AOwner parameter is the TListVew instance that uses the TListColumns object to implement its Columns property.


TListColumns::~TListColumns

TListColumns

~TListColumns frees the memory associated with the TListColumns object.

__fastcall virtual ~TListColumns(void) { }

Description

Do not call ~TListColumns directly. Instead, use the delete keyword on the object, which causes ~TListColumns to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


TListItems

Hierarchy	Properties	Methods	See also

TListItems maintains the list of items that appear in a list view control.

Unit

comctrls

Description

Use the properties and methods of TListItems to manipulate the list of items displayed by a list view control. TListItems only lists the main items in the list view. Subitems are specified using a property of the individual TListItem objects.


TListItems properties

TListItems	Alphabetically	Legend

In TListItems

Count

Handle

Item

Owner


TListItems properties

TListItems	By object	Legend

Count

Handle

Item

Owner


TListItems::Count

TListItems	See also

Indicates the number of items in the Item property array.

__property int Count = {read=GetCount, nodefault};

Description

Use Count to determine the number of items displayed by the list view. Count provides an upper bound when iterating through the individual TListItem objects in the Item property array.


TListItems::Handle

TListItems	See also

Specifies the window handle for the list view that displays the items managed by TListItems.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Use Handle as a parameter when making Windows API function calls that require a handle to the list view.


TListItems::Item

TListItems	See also

Lists all list items managed by the TListItems object.

__property TListItem* Item[int Index] = {read=GetItem, write=SetItem};

Description

Use Item to directly access a list item, given its position in the list view. The first item has an index of 0, the second an index of 1, and so on.


TListItems::Owner

TListItems	See also

Indicates the list view object that uses the list items object to manage its items.

__property TCustomListView* Owner = {read=FOwner};

Description

Use Owner to access the list view object that uses this TListItems object to implement its Items property.


TListItems methods

TListItems	Alphabetically

In TListItems

~TListItems

Add

Assign

BeginUpdate

Clear

Delete

EndUpdate

IndexOf

Insert

TListItems

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TListItems methods

TListItems	By object

~TListItems

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

EndUpdate

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

IndexOf

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TListItems


TListItems.Add
TListItems::Add

TListItems	See also 	Example

Creates a new list item and adds it to the list view control.

TListItem* __fastcall Add(void);

Description

Call Add to add a new list item to the end of the list. Add returns the newly created TListItem object.

To create an item and insert it into the beginning or middle of the list, use the Insert method instead.


TListItems::Assign

TListItems	See also

Copies the list of list items from another TListItems object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to copy the list of items from anther object. If the Source parameter specifies another TListItems object, Assign discards the current value of Item and rebuilds the list by copying the items maintained by Source. If Source is any other type of object, Assign calls the parent class's method, which will copy the list from any object that specifies how to copy to a TListItems object in its AssignTo method.


TListItems::BeginUpdate

TListItems	See also

Prevents updating of the list view until the EndUpdate method is called.

void __fastcall BeginUpdate(void);

Description

Call BeginUpdate before making multiple changes to the list of items. When all changes are complete, call EndUpdate so that the changes can be reflected on screen. BeginUpdate and EndUpdate prevent excessive redraws and speed processing time when new items are added, deleted, or inserted.


TListItems::Clear

TListItems	See also

Removes all items from the list.

void __fastcall Clear(void);

Description

Call Clear to empty the list view of all items. Clear frees all memory associated with the list items and updates the image of the list view.


TListItems::TListItems

TListItems	See also

Creates an instance of TListItems.

__fastcall TListItems(TCustomListView* AOwner);

Description

Call TListItems to instantiate a TListItems object at runtime. The TListItems object used by TListView to implement its Items property is created automatically from the constructor of the list view.


TListItems::Delete

TListItems	See also

Deletes a specified item and updates the list view accordingly.

void __fastcall Delete(int Index);

Description

The Delete method deletes the item in the list view specified with the Index parameter. The first item has an index of 0, the second item has an index of 1, and so on.


TListItems::~TListItems

TListItems	See also

Destroys an instance of TListItems.

__fastcall virtual ~TListItems(void);

Description

Do not call ~TListItems directly. Instead, an application should call Free, which verifies that the list items component is not already freed before calling ~TListItems.

~TListItems frees the list before calling the parent object’s destructor.


TListItems::EndUpdate

TListItems	See also

Reenables screen repainting that was turned off with the BeginUpdate method.

void __fastcall EndUpdate(void);

Description

Call EndUpdate after completing changes to the list that were begun with a call to the BeginUpdate method. When every call to BeginUpdate is matched by a subsequent call to EndUpdate, the list view image updates to reflect all changes that occurred while repaints were disabled.


TListItems::IndexOf

TListItems	See also

Returns the position of a list item in the list view window.

int __fastcall IndexOf(TListItem* Value);

Description

Call IndexOf to determine the position of the list item specified by the Value parameter. IndexOf returns -1 if the list item is not in the list view.


TListItems::Insert

TListItems	See also 	Example

Creates a new list item and inserts it into the list view.

TListItem* __fastcall Insert(int Index);

Description

Call Insert to insert a new TListItem object into the list view after the item specified by the Index parameter. Insert returns the list item that is inserted.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TListSourceLink

Hierarchy	Properties	Methods	See also

TListSourceLink helps manage the link to the ListSource of a TDBLookupControl object.

Unit

dbctrls

Description

TListSourceLink is tailored to work with TDBLookupControl. It should only be used by the TDBLookupControl class.


TListSourceLink properties

TListSourceLink	Alphabetically	Legend

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TListSourceLink properties

TListSourceLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TListSourceLink methods

TListSourceLink	Alphabetically	Legend

In TListSourceLink

~TListSourceLink

ActiveChanged

DataSetChanged

TListSourceLink

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TListSourceLink methods

TListSourceLink	By object	Legend

~TListSourceLink

ActiveChanged

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DataSetChanged

DefaultHandler

Dispatch

Edit

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TListSourceLink

UpdateRecord


TListSourceLink::ActiveChanged

TListSourceLink	See also

Informs the TDBLookupControl of changes to the Active property of the dataset that it maintains for the ListSource.

virtual void __fastcall ActiveChanged(void);

Description

Applications should not call the ActiveChanged procedure directly. Changes in the Active property of the dataset trigger this procedure. ActiveChanged causes the TDBLookupControl to reacquire its lookup list.


TListSourceLink::DataSetChanged

TListSourceLink	See also

Informs the TDBLookupControl of changes to the current record of the dataset that the TDBLookupControl uses to populate its list.

virtual void __fastcall DataSetChanged(void);

Description

Applications should not call the DataSetChanged procedure directly. These calls are triggered automatically by the dataset. DataSetChanged informs the TListSourceLink of dataset changes so that it can move to the appropriate record in the dataset.


Accessibility

Read-only


TListSourceLink::TListSourceLink

TListSourceLink

Creates a new TListSourceLink object.

__fastcall TListSourceLink(void) : Db::TDataLink() { }

Description

Do not create instances of TListSourceLink. A TListSourceLink object is created automatically from the constructor of the TDBLookupControl object that uses it.


TListSourceLink::~TListSourceLink

TListSourceLink

~TListSourceLink frees the memory associated with the TListSourceLink object.

__fastcall virtual ~TListSourceLink(void) { }

Description

Do not call ~TListSourceLink. TListSourceLink objects are only used by TDBLookupControl objects. TDBLookupControl handles the creation and destruction of its TListSourceLink object.


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


 TMainMenu

Hierarchy	Properties	Methods	See also

TMainMenu encapsulates a menu bar and its accompanying drop-down menus for a form.

Unit

menus

Description

Use TMainMenu to provide the main menu for a form. To begin designing a menu, add a main menu to a form, and double-click the component.

TMainMenu introduces properties and methods for merging the drop-down menus of the main menu with the main menu of another form, and for assisting in the menu negotiation process of an OLE container.


TMainMenu properties

TMainMenu	Alphabetically	Legend

In TMainMenu

AutoMerge

Handle

Derived from TMenu

Items

WindowHandle

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TMainMenu properties

TMainMenu	By object	Legend

AutoMerge

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Handle

Items

Name

Owner

Tag

VCLComObject

WindowHandle


TMainMenu::AutoMerge

TMainMenu	See also

Determines if the main menus of secondary forms merge with the main menu of the main form in non-MDI applications at runtime.

__property bool AutoMerge = {read=FAutoMerge, write=SetAutoMerge, default=0};

Description

To merge a form's menus with the main menu in the main form, set the AutoMerge property of each main menu you want merged to true. Make sure that the AutoMerge property of the main menu of the main form (the one other menus are merged into) remains false. How menus merge depends on the value of the GroupIndex property for each menu item.

If the application is an MDI application (the FormStyle properties are set so the main form is a parent form and subsequent forms are child forms), menu merging occurs automatically without using the AutoMerge property.


TMainMenu::Handle

TMainMenu	See also

Provides access to the menu’s window handle.

__property HMENU Handle = {read=GetHandle, nodefault};

Description

Use the Handle property to call a Windows API function that requires a Windows menu handle.

For example, the following line uses the Windows API function HiliteMenuItem to highlight the first menu item in MainMenu1 on Form1.

If the menu has an associated OLE menu handle, Handle is the OLE2 menu handle. Otherwise, Handle is the Windows menu handle for the menu that contains exactly the elements described in the Items property.


TMainMenu methods

TMainMenu	Alphabetically

In TMainMenu

~TMainMenu

GetOle2AcceleratorTable

Merge

PopulateOle2Menu

SetOle2MenuHandle

TMainMenu

Unmerge

Derived from TMenu

DispatchCommand

DispatchPopup

FindItem

GetHelpContext

IsShortCut

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMainMenu methods

TMainMenu	By object

~TMainMenu

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

DispatchCommand

DispatchPopup

FieldAddress

FindComponent

FindItem

Free

FreeInstance

FreeNotification

FreeOnRelease

GetHelpContext

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetOle2AcceleratorTable

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsShortCut

Merge

MethodAddress

MethodName

NewInstance

PopulateOle2Menu

RemoveComponent

SafeCallException

SetOle2MenuHandle

TMainMenu

Unmerge


TMainMenu::GetOle2AcceleratorTable

TMainMenu	See also

Returns the main menu’s accelerator table.

void __fastcall GetOle2AcceleratorTable(HACCEL &AccelTable, int &AccelCount, const int * Groups, const int Groups_Size);

Description

Call GetOle2AcceleratorTable to obtain a handle to an accelerator table for all menu items with a GroupIndex value that appears in the Groups parameter. The AccelTable parameter is set to the accelerator table handle, and the AccelCount is set to the number of entries in the table. GetOle2AccleratorTable is used by OLE containers when merging menus.


TMainMenu::Merge

TMainMenu	See also

Combines the main menu of one form with the main menu of another in non-MDI applications.

void __fastcall Merge(TMainMenu* Menu);

Description

Call Merge to merge another main menu with this one. Specify the menu you want merged with this menu as the Menu parameter.

For example, to use the main menu of the first form in an application as the main menu for the application, call Merge to merge the main menu of any additional forms in the application with the main menu of the first form.

Depending on the value of the GroupIndex property of menu items on the main menu, the merged menu items can replace menu items on the menu bar, or insert menu items into the menu bar. See GroupIndex for information on how to do these things.

To merge and unmerge main menus automatically when other forms are displayed, change the value of the AutoMerge property to true on all forms whose menus should be merged in.


TMainMenu::PopulateOle2Menu

TMainMenu	See also

Populates an OLE menu with items from the main menu.

void __fastcall PopulateOle2Menu(HMENU SharedMenu, const int * Groups, const int Groups_Size, int * Widths, const int Widths_Size);

Description

Call PopulateOle2Menu to merge the menu items with GroupIndex values specified by the Groups parameter into the menu that uses the SharedMenu handle. PopulateOle2Menu appends all menu items in the specified groups to the menu, and increments the corresponding entries in the Widths array for every menu item appended. PopulateOle2Menu is used by OLE containers when merging menus.

Note:	PopulateOle2Menu populates the menu specified by the SharedMenu parameter but does not set this as the OLE menu associated with the menu.


TMainMenu::SetOle2MenuHandle

TMainMenu	See also

Associates the handle for an OLE menu with the main menu.

void __fastcall SetOle2MenuHandle(HMENU Handle);

Description

Call SetOle2MenuHandle to temporarily replace the menu of a form with the menu represented by the Handle parameter. To restore the original menu, call SetOle2MenuHandle with the Handle parameter set to 0. SetOle2MenuHandle allows an OLE container to use menu items provided by an OLE server.


TMainMenu::Unmerge

TMainMenu	See also

Reverses the merging of two menus in a non-MDI application.

void __fastcall Unmerge(TMainMenu* Menu);

Description

Call Unmerge to remove items from another main menu that were added using the Merge method. The Menu parameter is the merged menu whose items should be removed from the main menu.


TMainMenu::TMainMenu

TMainMenu	See also

TMainMenu creates a new TMainMenu object.

__fastcall virtual TMainMenu(Classes::TComponent* AOwner) : Menus::TMenu(AOwner) { }

Description

Call TMainMenu to instantiate a TMainMenu object at runtime. Menus placed on forms at design time are created automatically. TMainMenu sets the initial values for the menu component, including creating an Items property.


TMainMenu::~TMainMenu

TMainMenu	See also

~TMainMenu frees the memory associated with the TMainMenu object.

__fastcall virtual ~TMainMenu(void) { }

Description

Do not call ~TMainMenu directly. Instead, use the delete keyword on the object, which causes ~TMainMenu to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TMenu


TMask

Hierarchy	Methods	See also

TMask allows the comparison of strings containing wildcards to a file mask.

Unit

masks

Description

Use TMask to determine if a string matches the format described by a mask. The mask contains literal characters, wildcards that can match any character, and sets that match a single character that is included in the set.

Note:	Do not confuse TMask with the EditMask of a field or masked edit object. While both are used for comparing strings to a symbolic description of valid values, the special mask symbols and matching rules are completely different.


TMask methods

TMask	Alphabetically

In TMask

~TMask

Matches

TMask

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TMask methods

TMask	By object

~TMask

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

Matches

MethodAddress

MethodName

NewInstance

SafeCallException

TMask


TMask::TMask

TMask	See also

Creates an instance of TMask for a given mask.

__fastcall TMask(const System::AnsiString MaskValue);

Description

Call TMask indirectly, using the new keyword, to create a mask object for comparing strings to the mask given by the MaskValue parameter. A valid mask consists of literal characters, sets, and wildcards.

Each literal character must match a single character in the string. The comparison to literal characters is case-insensitive.

Each set begins with an opening bracket ([) and ends with a closing bracket (]). Between the brackets are the elements of the set. Each element is a literal character or a range. Ranges are specified by an initial value, a dash (-), and a final value. Do not use spaces or commas to separate the elements of the set. A set must match a single character in the string. The character matches the set if it is the same as one of the literal characters in the set, or if it is in one of the ranges in the set. A character is in a range if it matches the initial value, the final value, or falls between the two values. All comparisons are case-insensitive. If the first character after the opening bracket of a set is an exclamation point (!), then the set matches any character that is not in the set.

Wildcards are asterisks (*) or question marks (?). An asterisk matches any number of characters. A question mark matches a single arbitrary character.


TMask::~TMask

TMask	See also

Destroys an instance of TMask.

__fastcall virtual ~TMask(void);

Description

Do not call ~TMask directly in an application. Instead, use the delete keyword.

~TMask frees the memory used to store a parsed image of the mask.


TMask::Matches

TMask	See also

Indicates whether a specified string matches the mask.

bool __fastcall Matches(const System::AnsiString Filename);

Description

Call Matches to compare the Filename parameter to the mask that describes valid values. Matches returns true if the string matches the mask. Matches returns false if the string does not match the mask. Matches throws an exception if the mask is syntactically invalid.

The mask is set when the TMask object is created.

Tip:	While the VCL uses TMask to check the whether file names specify valid directories, the Filename parameter does not need to be a file name. TMask can be used to check strings against any syntactically correct mask.


Hierarchy

TObject


 TMaskEdit

Hierarchy	Properties	Methods	Events	See also

TMaskEdit implements a generic masked edit control.

Unit

mask

Description

Use a TMaskEdit object to put a masked edit control on your form. Masked edit controls validate the text the user enters against a mask that encodes the valid forms the text can take. The mask can also format text that is displayed to the user.

TMaskEdit implements the generic behavior introduced in TCustomMaskEdit. TMaskEdit publishes many of the properties and methods inherited from TCustomMaskEdit, but does not introduce any new behavior.


TMaskEdit properties

TMaskEdit	Alphabetically	Legend

Derived from TCustomMaskEdit

EditMask

EditText

IsMasked

MaxLength

Text

Derived from TCustomEdit

AutoSelect

AutoSize

BorderStyle

CanUndo

CharCase

Modified

PasswordChar

ReadOnly

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TMaskEdit properties

TMaskEdit	By object	Legend

Align

AutoSelect

AutoSize

BorderStyle

BoundsRect

Brush

CanUndo

CharCase

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

EditMask

EditText

Enabled

Font

Handle

Height

HelpContext

Hint

ImeMode

ImeName

IsMasked

Left

MaxLength

Modified

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PasswordChar

PopupMenu

ReadOnly

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

Width

WindowProc


TMaskEdit events

TMaskEdit	Alphabetically	Legend

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TMaskEdit events

TMaskEdit	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TMaskEdit methods

TMaskEdit	Alphabetically

In TMaskEdit

~TMaskEdit

TMaskEdit

Derived from TCustomMaskEdit

Clear

GetTextLen

ValidateEdit

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMaskEdit methods

TMaskEdit	By object

~TMaskEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TMaskEdit

Undo

Update

UpdateControlState

ValidateEdit


TMaskEdit::TMaskEdit

TMaskEdit

Creates a new TMaskEdit object.

__fastcall virtual TMaskEdit(Classes::TComponent* AOwner) : Mask::TCustomMaskEdit(AOwner) { }

__fastcall TMaskEdit(HWND ParentWindow) : Mask::TCustomMaskEdit(ParentWindow) { }

Description

Do not call TMaskEdit directly when creating a masked edit control at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TMaskEdit object. Masked edit controls placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TMaskEditControl object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the masked edit control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TMaskEdit::~TMaskEdit

TMaskEdit

~TMaskEdit frees the memory associated with the TMaskEdit object.

__fastcall virtual ~TMaskEdit(void) { }

Description

Do not call ~TMaskEdit directly. Instead, use the delete keyword on the object, which causes ~TMaskEdit to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMaskEdit


 TMediaPlayer

Hierarchy	Properties	Methods	Events

TMediaPlayer controls devices that provide a Media Control Interface (MCI) driver.

Unit

mplayer

Description

The TMediaPlayer component is a set of buttons (Play, Stop, Eject, and so on) that controls a multimedia device such as a CD-ROM drive, a MIDI sequencer, or a VCR. A multimedia device may be hardware or software.

The media player component consists of multiple buttons. These buttons can be clicked with the mouse, but are not separate objects or button components.

Button	Value	Action

Play	btPlay	Plays the media player.

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Stop	btStop	Stops playing or recording.

Next	btNext	Skips to the next track, or to the end if the medium doesn’t use tracks.

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn’t use tracks.

Step	btStep	Moves forward a number of frames.

Back	btBack	Moves backward a number of frames.

Record	btRecord	Starts recording.

Eject	btEject	Ejects the medium.

The multimedia device is played, paused, stopped, and so on when the user clicks the corresponding button on the TMediaPlayer component. The device can also be controlled by the control methods that correspond to the buttons (Play, Pause, Stop, Next, Previous, Step, Back, StartRecording, and Eject).

The type of multimedia device (such as dtWaveAudio or dtVideodisc) is specified by the DeviceType property. If the device stores its media in a file, the name of the media file is specified by the FileName property. If DeviceType is dtAutoSelect, the media player attempts to determine the type of device from the extension of the file specified by FileName.

To have the media player attempt to open the device specified by DeviceType automatically when the media player component is created at runtime, set the AutoOpen property to true.


TMediaPlayer properties

TMediaPlayer	Alphabetically	Legend

In TMediaPlayer

AutoEnable

AutoOpen

AutoRewind

Capabilities

ColoredButtons

DeviceID

DeviceType

Display

DisplayRect

EnabledButtons

EndPos

Error

ErrorMessage

FileName

Frames

Length

Mode

Notify

NotifyValue

Position

Shareable

Start

StartPos

TimeFormat

TrackLength

TrackPosition

Tracks

VisibleButtons

Wait

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TMediaPlayer properties

TMediaPlayer	By object	Legend

Align

AutoEnable

AutoOpen

AutoRewind

BoundsRect

Brush

Capabilities

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ColoredButtons

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DeviceID

DeviceType

Display

DisplayRect

Enabled

EnabledButtons

EndPos

Error

ErrorMessage

FileName

Frames

Handle

Height

HelpContext

Hint

Left

Length

Mode

Name

Notify

NotifyValue

Owner

Parent

ParentShowHint

ParentWindow

PopupMenu

Position

Shareable

ShowHint

Showing

Start

StartPos

TabOrder

TabStop

Tag

TimeFormat

Top

TrackLength

TrackPosition

Tracks

VCLComObject

Visible

VisibleButtons

Wait

Width

WindowProc


TMediaPlayer::AutoEnable

TMediaPlayer	See also 	Example

Determines whether the media player automatically enables and disables individual buttons in the component.

__property bool AutoEnable = {read=FAutoEnable, write=SetAutoEnable, default=1};

Description

Use AutoEnable to automatically enable or disable the control buttons on the media player. If AutoEnable is true, the media player automatically enables or disables its control buttons. The media player determines which buttons to enable or disable by the current mode specified in the Mode property, and the current multimedia device type specified in the DeviceType property.

AutoEnable overrides the EnabledButtons property. The buttons enabled or disabled automatically by the media player supersede any buttons enabled or disabled with EnabledButtons.

If AutoEnable is false, the media player does not enable or disable buttons. The buttons must enabled or disabled with the EnabledButtons property.

The following table shows whether buttons are automatically enabled or disabled for each device mode:

Button	Play	Record	Pause	Stop	Not Open

Back	Enabled	Enabled	Enabled	Enabled	Disabled

Eject	Enabled	Enabled	Enabled	Enabled	Disabled

Next	Enabled	Enabled	Enabled	Enabled	Disabled

Pause	Enabled	Enabled	Enabled	Disabled	Disabled

Play	Disabled	Disabled	Enabled	Enabled	Disabled

Prev	Enabled	Enabled	Enabled	Enabled	Disabled

Record	Disabled	Disabled	Enabled	Enabled	Disabled

Step	Enabled	Enabled	Enabled	Enabled	Disabled

Stop	Enabled	Enabled	Disabled	Disabled	Disabled


TMediaPlayer::AutoOpen

TMediaPlayer	See also

Determines if the media player is opened automatically when the application is run.

__property bool AutoOpen = {read=FAutoOpen, write=FAutoOpen, default=0};

Description

Use AutoOpen to have the media player automatically open at runtime.

If AutoOpen is true, the media player attempts to open the multimedia device specified by the DeviceType property (or FileName if DeviceType is dtAutoSelect) when the form containing the media player component is created at runtime.

If AutoOpen is false, the device must be opened with a call to the Open method.

If an error occurs when opening the device, an exception of type EMCIDeviceError exception is thrown which contains the error message. Upon completion, a numerical error code is stored in the Error property, and the corresponding error message is stored in the ErrorMessage property.

The Wait property determines whether control is returned to the application before opening the multimedia device. The Notify property determines whether opening the device generates an OnNotify event.


TMediaPlayer::AutoRewind

TMediaPlayer	See also 	Example

Determines if the media player control rewinds before playing or recording.

__property bool AutoRewind = {read=FAutoRewind, write=FAutoRewind, default=1};

Description

If AutoRewind is true and the current position is at the end of the medium, Play or StartRecording moves the current position to the beginning of the medium before playing or recording. If AutoRewind is false, the user must click the Prev button or write code to call Previous to move to the beginning.

Note:	If values have been assigned to StartPos or EndPos or if the multimedia device uses tracks, AutoRewind has no effect on playing or recording. When calling Play or StartRecording, the current position remains at the end of the medium.


TMediaPlayer::Capabilities

TMediaPlayer	See also 	Example

Determines the capabilities of the open multimedia device.

__property TMPDevCapsSet Capabilities = {read=FCapabilities, nodefault};

Description

The various capabilities specified in Capabilities are determined when the device is opened with the Open method. The following table lists the capabilities a device can have:

Value	Capability

mpCanEject	Can eject media

mpCanPlay	Can play media

mpCanRecord	Can record media

mpCanStep	Can step forward or backward within media

mpUsesWindow	Uses a window for displaying output

Note:	Currently, there is no way to check whether a device can step forward or backward. Capabilities includes mpCanStep only if the device type (specified in the DeviceType property) is Animation, AVI Video, Digital Video, Overlay, or VCR.


TMediaPlayer::ColoredButtons

TMediaPlayer	See also

Determines which of the buttons on the media player control has color.

__property TButtonSet ColoredButtons = {read=FColoredButtons, write=SetColored, default=511};

Description

ColoredButtons controls which buttons on the media player are colored.

If a button is not colored with ColoredButtons, it appears in black-and-white when visible. All media player control buttons are colored by default.

Button	Value	Action

Play	btPlay	Plays the media player.

Record	btRecord	Starts recording.

Stop	btStop	Stops playing or recording.

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks.

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks.

Step	btStep	Moves forward a number of frames.

Back	btBack	Moves backward a number of frames.

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium.


TMediaPlayer::DeviceID

TMediaPlayer	See also

Specifies the device ID for the currently open multimedia device.

__property Word DeviceID = {read=FDeviceID, nodefault};

Description

The value of DeviceID is determined when an device is opened with the Open method. If no device is open, DeviceID is 0.


TMediaPlayer::DeviceType

TMediaPlayer	See also 	Example

Specifies a multimedia device type to open the media player.

__property TMPDeviceTypes DeviceType = {read=FDeviceType, write=SetDeviceType, default=0};

Description

DeviceType specifies a multimedia device type to open with the Open method.

TMPDeviceTypes type contains the multimedia device types that can be opened by a TMediaPlayer component. The valid values for TMPDeviceTypes are dtAutoSelect, dtAVIVideo, dtCDAudio, dtDAT, dtDigitalVideo, dtMMMovie, dtOther, dtOverlay, dtScanner, dtSequencer, dtVCR, dtVideodisc, or dtWaveAudio. The default is dtAutoSelect.

If DeviceType is dtAutoSelect, the device type is determined by the file extension specified in the FileName property. If no device type is associated with the extension, the correct device type must be explicitly specified by setting DeviceType to a value other than dtAutoSelect.

A multimedia device is typically associated with an appropriate file name extension when the device is installed. Associations are specified in the registry or SYSTEM.INI file. See the documentation for the specific device for instructions about how to associate file name extensions with the device.


TMediaPlayer::Display

TMediaPlayer 	See also	Example

Specifies the display window for an multimedia device that uses a window for output.

__property Controls::TWinControl* Display = {read=FDisplay, write=SetDisplay};

Description

To use Display, assign the name of a windowed control such as a form or panel to Display to display output in that control.

The default value of Display is NULL, meaning that the device creates its own window to display output. Also, by freeing the control assigned to Display after the device has been opened, video output will be in its own default window.

Examples of multimedia devices that use a window to display output are Animation, AVI Video, Digital Video, Overlay, and VCR.


TMediaPlayer::DisplayRect

TMediaPlayer	See also

Specifies a rectangular area in the control specified by the Display property that is used to display output from a multimedia device.

__property Windows::TRect DisplayRect = {read=GetDisplayRect, write=SetDisplayRect};

Description

To display output in a specific rectangle area on a form assign a TRect record to DisplayRect. The Rect function can be used to create a TRect record.

Media that use a rectangle to display output usually perform best if the default DisplayRect size is used. To set DisplayRect to the default size, position the rectangle in the upper left corner and use 0, 0 for the lower right corner.

DisplayRect is ignored if Display is NULL.

Examples of multimedia devices that use a window to display output are Animation, AVI Video, Digital Video, Overlay, and VCR.

Note:	DisplayRect can only be set after the media device is opened.


TMediaPlayer::EnabledButtons

TMediaPlayer	See also 	Example

Determines which buttons on the media player are usable.

__property TButtonSet EnabledButtons = {read=FEnabledButtons, write=SetEnabledButtons, default=511}

Description

EnabledButtons controls which buttons on the media player are enabled and usable.

An enabled button is colored and usable. A disabled button is dimmed and not usable. If a button is not enabled with EnabledButtons, it is disabled. By default, all buttons are enabled.

If the AutoEnable property is true, AutoEnable supersedes EnabledButtons. The buttons automatically enabled or disabled by the media player override any buttons enabled or disabled with the EnabledButtons property.

Button	Value	Action

Play	btPlay	Plays the media player

Record	btRecord	Starts recording

Stop	btStop	Stops playing or recording

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks

Step	btStep	Moves forward a number of frames

Back	btBack	Moves backward a number of frames

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium


TMediaPlayer::EndPos

TMediaPlayer	See also 	Example

Specifies the position within the currently loaded medium at which to stop playing or recording.

__property int EndPos = {read=FTo, write=SetTo, nodefault};

Description

EndPos is specified using the current time format, which is specified in the TimeFormat property.

The EndPos property affects only the next Play or StartRecording method called after setting EndPos. Reset EndPos to affect any subsequent calls to Play or StartRecording.


TMediaPlayer::Error

TMediaPlayer	See also 	Example

Specifies the MCI error code returned by the media control method.

__property int Error = {read=FError, nodefault};

Description

Error specifies the MCI error code returned by the most recent media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop). The ErrorMessage property describes the Error.

The error code returned by media control methods are the same error code returned by the mciSendCommand function. The message describing the error code is stored in the ErrorMessage property.

The value of Error is zero if the most recent media control method didn't cause an error. If a method results in an error, a value other than zero is stored in Error. If the error occurs during the opening of the device, an EMCIDeviceError exception occurs.


TMediaPlayer::ErrorMessage

TMediaPlayer	See also 	Example

Describes the error code stored in the Error property.

__property System::AnsiString ErrorMessage = {read=GetErrorMessage};

Description

ErrorMessage specifies the error message that describes the error code returned from the most recent media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop).

The error code described by the message is stored in the Error property.


TMediaPlayer::FileName

TMediaPlayer	See also 	Example

Specifies the opened or saved media file.

__property System::AnsiString FileName = {read=FElementName, write=FElementName};

Description

FileName specifies the media file to be opened by the Open method, or the file to save by the Save method.

At design time, use a file open dialog box to specify the FileName property by clicking the ellipses button (.::::) in the Object Inspector.


TMediaPlayer::Frames

TMediaPlayer	See also

Specifies the number of frames moved forward or backward.

__property int Frames = {read=FFrames, write=FFrames, nodefault};

Description

Frames specifies the number of frames the Step method steps forward or the Back method steps backward.

Frames defaults to ten percent of the length of the currently loaded medium, which is specified by the Length property.

Note:	The definition of frame varies by multimedia device. For display media, a frame is one still image.


TMediaPlayer::Length

TMediaPlayer	See also 	Example

Specifies the length of the medium in the open multimedia device.

__property int Length = {read=GetLength, nodefault};

Description

Length is specified using the current time format, which is specified by the TimeFormat property.


TMediaPlayer::Mode

TMediaPlayer 	See also Example

Indicates the state of the currently open multimedia device.

__property TMPModes Mode = {read=GetMode, nodefault};

Description

Mode specifies the current state or mode of the currently open multimedia device.

The TMPModes type defines the modes for a multimedia device used with a TMediaPlayer.

The following table lists the possible values for of the TMPModes type:

Value	Mode

mpNotReady	Not ready

mpStopped	Stopped

mpPlaying	Playing

mpRecording	Recording

mpSeeking	Seeking

mpPaused	Paused

mpOpen	Open


TMediaPlayer::Notify

TMediaPlayer	See also	Example

Determines whether an OnNotify event is generated.

__property bool Notify = {read=FNotify, write=SetNotify, nodefault};

Description

Notify determines whether the next call to a media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop) generates an OnNotify event when the method has completed.

If Notify is true, the next media control method generates OnNotify event upon completion and stores the notification message in the NotifyValue property. If Notify is false, the method does not generate an OnNotify event and NotifyValue remains unchanged.

Notify affects only the next call to a media control method. After an OnNotify event, Notify must be reset to affect any subsequent media control methods.

By default, Play and StartRecording function as if Notify is true. Set Notify to false before calling Play or StartRecording to prevent an OnNotify event from being generated when playing or recording has finished. By default, all other media control methods function as if Notify is false.

Tip:	Set Notify to true if the next media control is expected to take a long time, so the application is notified when the media control method has completed. If Notify is set to true, it is recommended to set Wait to false so that control returns to the application before the media control method is finished.

Note:	When trying to resume a device that doesn't support Resume, the device is resumed as if the Play method was called. If Notify was assigned true before calling Resume (or any other media control method), Notify doesn't affect the call to Resume. Resume does not generate an OnNotify event upon completion, and NotifyValue remains unchanged.


TMediaPlayer::NotifyValue

TMediaPlayer 	See also Example

Indicates the result of the last media control method that requested a notification.

__property TMPNotifyValues NotifyValue = {read=FNotifyValue, nodefault};

Description

NotifyValue reports the result of the last media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop) that requested a notification.

To request notification, set Notify to true before calling a media control method.

The TMPNotifyValues type defines the notification values for a multimedia device used with a TMediaPlayer. The possible values for the TMPNotifyValues type are as follows.

Value	Result

nvSuccessful	Command completed successfully

nvSuperseded	Command was superseded by another command

nvAborted	Command was aborted by the user

nvFailure	Command failed


TMediaPlayer::Position

TMediaPlayer	See also

Specifies the current position within the currently loaded medium.

__property int Position = {read=GetPosition, write=SetPosition, nodefault};

Description

The value of Position is specified according to the current time format, which is specified in the TimeFormat property.

Position defaults to the beginning of the medium. If the medium supports multiple tracks, Position defaults to the beginning of the first track.


TMediaPlayer::Shareable

TMediaPlayer	See also 	Example

Determines whether more than one application can share a multimedia device.

__property bool Shareable = {read=FShareable, write=FShareable, default=0};

Description

If Shareable is false, no other components or applications can access the device. If Shareable is true, more than one component or application can access the device. Shareable defaults to false.

Be sure to set Shareable before opening a device. Some devices aren't shareable::Setting Shareable to true and trying to open a device that isn't shareable by more than one application, the Open method fails and the error code is returned to the Error property.


TMediaPlayer::Start

TMediaPlayer	See also

Specifies the starting position within the currently loaded medium.

__property int Start = {read=GetStart, nodefault};

Description

Start is the beginning of the medium for devices that don't use tracks, or the beginning of the first track for devices that use tracks. Start is defined when a multimedia device is opened with the Open method. Start is specified according to the current time format, which is stored in the TimeFormat property. Start is read-only at runtime and is unavailable at design time.


TMediaPlayer::StartPos

TMediaPlayer	See also

Specifies the position within the currently loaded medium from which to begin playing or recording.

__property int StartPos = {read=FFrom, write=SetFrom, nodefault};

Description

StartPos is specified using the current time format, which is specified in the TimeFormat property.

The StartPos property affects only the next Play or StartRecording method called after setting StartPos. Reset must be set to StartPos to affect any subsequent calls to Play or StartRecording.

StartPos does not affect the current position of the medium (specified in the Position property) until the next Play or StartRecording method is called.


TMediaPlayer::TimeFormat

TMediaPlayer	See also 	Example

Determines the format used to specify position information.

__property TMPTimeFormats TimeFormat = {read=GetTimeFormat, write=SetTimeFormat, nodefault};

Description

TimeFormat determines how the StartPos, Length, Position, Start, and EndPos properties are interpreted. For example, if Position is 180 and TimeFormat is tfMilliseconds, the current position is 180 milliseconds into the medium. If Position is 180 and TimeFormat is tfMSF, the current position is 180 minutes into the medium.

Not all formats are supported by every device. When trying to set an unsupported format, the assignment is ignored.

The current timing information is always passed in a 4-byte integer. In some formats, the timing information returned is not really one integer, but single bytes of information packed in the long integer.

The TMPTimeFormats type defines the time formats for a multimedia device used with a TMediaPlayer. The following table lists the possible values for the TMPTimeFormats type:

Value	Time format

tfMilliseconds	Milliseconds are stored as a 4-byte integer variable.

tfHMS	Hours, minutes, and seconds packed into a 4-byte integer. From least significant to most significant byte, the data values are

  Hours (least significant byte)

  Minutes

  Seconds

  Unused (most significant byte)

tfMSF	Minutes, seconds, and frames packed into a 4-byte integer. From least significant to most significant byte, the data values are

  Minutes (least significant byte)

  Seconds

  Frames

  Unused (most significant byte)

tfFrames	Frames are stored as a 4-byte integer variable.

tfSMPTE24	24-frame SMPTE packs values in a 4-byte variable. From least significant to most significant byte, the data values are

  Hours (least significant byte)

  Minutes

  Seconds

  Frames (most significant byte)

SMPTE (Society of Motion Picture and Television Engineers) time is an absolute time format expressed in hours, minutes, seconds, and frames. The standard SMPTE division types are 24, 25, and 30 frames per second.

tfSMPTE25	25-frame SMPTE packs data into a 4-byte variable in the same order as 24-frame SMPTE.

tfSMPTE30	30-frame SMPTE packs data into the 4-byte variable in the same order as 24-frame SMPTE.

tfSMPTE30Drop	30-drop-frame SMPTE packs data into the 4-byte variable in the same order as 24-frame SMPTE.

tfBytes	Bytes are stored as a 4-byte integer variable.

tfSamples	Samples are stored as a 4-byte integer variable.

tfTMSF	Tracks, minutes, seconds, and frames are packed in the 4-byte variable. From least significant to most significant byte, the data values are

Tracks (least significant byte)
Minutes
Seconds
Frames (most significant byte)

Note that MCI uses continuous track numbering.

Note:	Functions provided with MCI to help decoding the 4-byte integer specified in a given time format are documented under MCI Macros for Encoding and Decoding Time Data in the MMSYSTEM.HLP Help file.


TMediaPlayer::TrackLength

TMediaPlayer	See also 	Example

Reports the length of the track.

__property int TrackLength[int TrackNum] = {read=GetTrackLength};

Description

TrackLength reports the length of the track specified by the TrackNum index.

The value of TrackLength is specified according to the current time format, which is specified in the TimeFormat property.


TMediaPlayer::TrackPosition

TMediaPlayer	See also

Reports the starting position of the track.

__property int TrackPosition[int TrackNum] = {read=GetTrackPosition};

Description

TrackPosition reports the starting position of the track specified by the TrackNum index.

The value of TrackPosition is specified according to the current time format, which is specified in the TimeFormat property.


TMediaPlayer::Tracks

TMediaPlayer 	See also

Specifies the number of playable tracks on the open multimedia device.

__property int Tracks = {read=GetTracks, nodefault};

Description

Tracks indicates how many of playable tracks are available on the open multimedia device.

Tracks is undefined for devices that don't use tracks.


TMediaPlayer::VisibleButtons

TMediaPlayer	See also 	Example

Indicates which of the buttons on the media player are visible.

__property TButtonSet VisibleButtons = {read=FVisibleButtons, write=SetVisible, default=511};

Description

VisibleButtons determines the buttons on the media player that are visible. If a button is not made visible with VisibleButtons, it does not appear on the media player control. By default, all buttons are visible when a media player component is added to a form.

Button	Value	Action

Play	btPlay	Plays the media player.

Record	btRecord	Starts recording.

Stop	btStop	Stops playing or recording.

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks.

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks.

Step	btStep	Moves forward a number of frames.

Back	btBack	Moves backward a number of frames.

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium.


TMediaPlayer::Wait

TMediaPlayer 	See also	Example

Determines whether a media control method returns control to the application only after it has been completed.

__property bool Wait = {read=FWait, write=SetWait, nodefault};

Description

Wait determines whether a media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, StartRecording, Resume, Rewind, Step, or Stop) returns control to the application only after it has been completed.

Wait is unavailable at design time.

If Wait is true, the media player component waits until the next media control method has completed before returning control to the application. If Wait is false, the application won't wait for the next media control method to finish before continuing.

Wait affects only the next media control method called after setting Wait. Wait must be reset to affect any subsequent call to a media control method.

By default, Play and StartRecording function as if Wait is false. Wait must be set to true before calling Play or StartRecording to prevent control from returning to the application before playing or recording has finished. By default, all other media control methods function as if Wait is true.

Note:	Wait is usually set to false only if the next media control is expected to take a long time, so that the application can execute other code before the media control method has completed. If Wait is set to false, you should set Notify to true so the application is notified when the media control method completes.


TMediaPlayer events

TMediaPlayer	Alphabetically	Legend

In TMediaPlayer

OnClick

OnNotify

OnPostClick

Derived from TWinControl

OnEnter

OnExit


TMediaPlayer events

TMediaPlayer	By object	Legend

OnClick

OnEnter

OnExit

OnNotify

OnPostClick


TMediaPlayer::OnClick

TMediaPlayer	See also 	Example

Occurs when the user presses and releases the mouse button while the mouse pointer is over one of the control buttons, or when the user presses Spacebar while the media player control has focus.

__property EMPNotify OnClick = {read=FOnClick, write=FOnClick};

Description

When the media player control has focus and the Spacebar is pressed, the user can use the Left Arrow or Right Arrow keys to select which control button to click.

The EMPNotify type is a method pointer that is called when an OnClick event for a TMediaPlayer components occurs. The Button argument can be one of the following values: btBack, btEject, btNext, btPause, btPlay, btPrev, btRecord, btStep, or btStop.

The default value of the DoDefault argument is true. If DoDefault is true, the media player control calls the method that corresponds to the clicked button. For example, if the user clicks the Play button (btPlay), the Play method is called.

If DoDefault is false, the user must write code that executes when a media player control button is clicked in the OnClick event handler. The following table lists the default methods corresponding to the media player control buttons:

Control button	Button value	Method called

Play	btPlay	Play

Record	btRecord	StartRecording

Stop	btStop	Stop

Next	btNext	Next

Prev	btPrev	Previous

Step	btStep	Step

Back	btBack	Back

Pause	btPause	Pause

Eject	btEject	Eject


TMediaPlayer::OnNotify

TMediaPlayer	See also	Example

Occurs upon the completion of a media control method.

__property Classes::TNotifyEvent OnNotify = {read=FOnNotify, write=FOnNotify};

Description

OnNotify occurs upon the completion of a media control method (Back, Close, Eject, Next, Open, Pause, PauseOnly, Play, Previous, Resume, Rewind, StartRecording, Step, or Stop) when the Notify property is set to true before the call to the media control method. After an OnNotify event, the Notify property must be reset to true for the next OnNotify event to occur.


TMediaPlayer::OnPostClick

TMediaPlayer	See also

Occurs after the OnClick event handler is called.

__property EMPPostNotify OnPostClick = {read=FOnPostClick, write=FOnPostClick};

Description

OnPostClick is generated after the code of the OnClick event handler has been called. If Wait is true when the media player was clicked, OnPostClick won't be called until the completion of the OnClick code. If Wait is false, control can return to the application before completion of the OnClick code; therefore, the OnPostClick event may occur before the actions initiated by the OnClick event have completed.

For example, if the user clicks the Play button and the DoDefault parameter of the OnClick event handler for the media player is true, the media is played. If the media is long enough, it will still be playing when the OnPostClick event is generated if Wait is true. If Wait is false, however, OnPostClick won't occur until the media has finished playing.

The EMPPostNotify type is a method that is called when an OnPostClick event for a TMediaPlayer component occurs. The Button argument can be one of the following values: btBack, btEject, btNext, btPause, btPlay, btPrev, btRecord, btStep, or btStop.


TMediaPlayer methods

TMediaPlayer	Alphabetically	Legend

In TMediaPlayer

~TMediaPlayer

AutoButtonSet

Back

Click

Close

DoNotify

Eject

KeyDown

Loaded

MMNotify

Next

Notification

Open

Paint

Pause

PauseOnly

Play

PostClick

Previous

Resume

Rewind

Save

StartRecording

Step

Stop

TMediaPlayer

Updated

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMediaPlayer methods

TMediaPlayer	By object	Legend

~TMediaPlayer

Assign

AutoButtonSet

Back

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

Close

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DoNotify

DragDrop

Dragging

Eject

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

KeyDown

Loaded

MethodAddress

MethodName

MMNotify

NewInstance

Next

Notification

Open

Paint

PaintTo

Pause

PauseOnly

Perform

Play

PostClick

Previous

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

Resume

Rewind

SafeCallException

Save

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

StartRecording

Step

Stop

TMediaPlayer

Update

UpdateControlState

Updated


TMediaPlayer::AutoButtonSet

TMediaPlayer	See also

Enables or Disables the media player’s buttons.

DYNAMIC void __fastcall AutoButtonSet(TMPBtnType Btn);

Description

AutoButtonSet implements the automatic enabling and disabling of the media player's buttons when the AutoEnable property is true. The Btn parameter indicates which of the media player's buttons the user pressed.

TMPBtnType is the type of the Btn parameter. The values for TMPBtnType are as follows:

Button	Value	Action

Play	btPlay	Plays the media player.

Record	btRecord	Starts recording.

Stop	btStop	Stops playing or recording.

Next	btNext	Skips to the next track, or to the end if the medium doesn't use tracks.

Prev	btPrev	Skips to the previous track, or to the beginning if the medium doesn't use tracks.

Step	btStep	Moves forward a number of frames.

Back	btBack	Moves backward a number of frames.

Pause	btPause	Pauses playing or recording. If already paused when clicked, resumes playing or recording.

Eject	btEject	Ejects the medium.


TMediaPlayer::Back

TMediaPlayer	See also 	Example

Steps backward a number of frames (determined by the value of the Frames property) in the currently loaded medium.

void __fastcall Back(void);

Description

Back is called when the Back button on the media player control is clicked at runtime.

Upon completion, Back stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Back method has been completed. The Notify property determines whether Back generates an OnNotify event.


TMediaPlayer::Click

TMediaPlayer	See also

Generates an OnClick event.

HIDESBASEDYNAMIC void __fastcall Click(TMPBtnType Button, bool &DoDefault);

Description

Click for media-player components is the implementation method for the OnClick event. By default, Click does nothing other than call any event handler attached to the media player's OnClick event. Click can be overriden in descendant types to customize responses to clicks.


TMediaPlayer::Close

TMediaPlayer	See also 	Example

Closes the open multimedia device.

void __fastcall Close(void);

Description

Upon completion, Close stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Close method is completed. The Notify property determines whether Close generates an OnNotify event.

Close is called automatically when the application is terminated.


TMediaPlayer::TMediaPlayer

TMediaPlayer	See also

Creates a media player object.

__fastcall virtual TMediaPlayer(Classes::TComponent* AOwner);

__fastcall TMediaPlayer(HWND ParentWindow) : Controls::TCustomControl(ParentWindow) { }

Description

Call TMediaPlayer indirectly, using the new keyword, to instantiate a media player at runtime. For media players created at design time, TMediaPlayer is called automatically.

TMediaPlayer allocates memory for a media player, and calls the parent object’s constructor.

Then it loads the bitmaps used for its buttons and sets intial values for the media player including setting the AutoEnable, AutoRewind, Colored, Enabled, and Visible properties to true, AutoOpen to false, and DeviceType to dtAutoSelect.


TMediaPlayer::~TMediaPlayer

TMediaPlayer	See also

Destroys an instance of the media player.

__fastcall virtual ~TMediaPlayer(void);

Description

Do not call ~TMediaPlayer directly in an application. Instead, an application should call the delete keyword.

~TMediaPlayer ensures that no device is open before it destroys the bitmaps, used for the media player’s buttons, and then calls the parent object’s destructor.


TMediaPlayer::DoNotify

TMediaPlayer	See also

Generates an OnNotify event.

DYNAMIC void __fastcall DoNotify(void);

Description

DoNotify is the implementation method for a media-player component's OnNotify event. The media player's MMNotify method calls DoNotify after correcting the enabling and disabling of buttons and setting internal flags from the values passed in the notification message parameters.

By default, DoNotify does nothing except call any event handler attached to the media player's OnNotify event. DoNotify can be overridden to provide other responses in addition to the parent class's event-handler call.


TMediaPlayer::Eject

TMediaPlayer	See also 	Example

Releases the loaded medium from the open multimedia device.

void __fastcall Eject(void);

Description

Eject is called when the Eject button on the media player control is clicked at runtime. It ejects the loaded medium from the open multimedia device.

Upon completion, Eject stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Eject method has been completed. The Notify property determines whether Eject generates an OnNotify event.


TMediaPlayer::KeyDown

TMediaPlayer	See also

Provides responses when the user types arrow keys or the space bar.

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

KeyDown overrides the parent class's method to implement the media player’s response to certain keystrokes.  It changes the current button when the user types the left or right arrow keys. When the user presses the space bar, KeyDown simulates a click on the current button.


TMediaPlayer::Loaded

TMediaPlayer	See also

Initializes the media plater after it is loaded from a stream.

virtual void __fastcall Loaded(void);

Description

Loaded provides an opportunity for a component to initialize itself after all its parts have loaded from a stream. TMediaPlayer overrides the parent class's method to implement the AutoOpen property.


TMediaPlayer::Next

TMediaPlayer	See also 	Example

Moves to the beginning of the next track of the currently loaded medium.

void __fastcall Next(void);

Description

If the current position is at the last track when Next is called, Next makes the current position the beginning of the last track. If the multimedia device doesn't use tracks, Next goes to the end of the medium. Next is called when the Next button on the media player control is clicked at runtime.

Upon completion, Next stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Next method has completed. The Notify property determines whether Next generates an OnNotify event.


TMediaPlayer::MMNotify

TMediaPlayer	See also

Responds to a notification that the MCI device has completed an operation.

MESSAGE void __fastcall MMNotify(Messages::TMessage &Message);

Description

MMNotify responds to a notification message from Windows that a multimedia command completed by updating button states if the AutoEnable property is true, setting internal flags to reflect the outcome of the command, then calling the DoNotify method to trigger the OnNotify event and any other special responses.


TMediaPlayer::Notification

TMediaPlayer	See also

Responds when components are about to be inserted or removed.

virtual void __fastcall Notification(Classes::TComponent* AComponent, Classes::TOperation Operation);

Description

By default, components pass along the notification to their owned components, if any. Notification calls the parent class's Notification and then, if the Display window is deleted at runtime, it sets the video display back to original window.


TMediaPlayer::Open

TMediaPlayer	See also 	Example

Opens a multimedia device.

void __fastcall Open(void);

Description

Use Open to open a multimedia device. The multimedia device type must be specified in the DeviceType property before a device can be opened.

Upon completion, Open stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Open method is completed. The Notify property determines whether Open generates an OnNotify event.


TMediaPlayer::Paint

TMediaPlayer 	See also

Renders the image of the media player.

virtual void __fastcall Paint(void);

Description

When the media player component receives a WM_PAINT message, like other custom controls, it responds by initializing the control's canvas and calling Paint. Paint draws the frame and all visible buttons.

When creating a descendant media player class, Paint can be overriden to draw the image of the corresponding media player object.


TMediaPlayer::PostClick

TMediaPlayer	See also

Determines the action that takes place when an OnPostClick event occurs.

DYNAMIC void __fastcall PostClick(TMPBtnType Button);

Description

PostClick is the implementation method for the OnPostClick event. By default, PostClick does nothing other than call any event handler attached to the media player's OnPostClick event. PostClick can be overriden in descendant types to customize responses to clicks.


TMediaPlayer::Pause

TMediaPlayer	See also 	Example

Toggles the open multimedia device on or off.

void __fastcall Pause(void);

Description

If the device is already paused when Pause is called, the device resumes playing or recording by calling the Resume method. Pause is called when the Pause button on the media player control is clicked at runtime.

Upon completion, Pause stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Pause method has completed. The Notify property determines whether Pause generates an OnNotify event.


TMediaPlayer::PauseOnly

TMediaPlayer	See also 	Example

Pauses the open multimedia device.

void __fastcall PauseOnly(void);

Description

If the device is already paused when PauseOnly is called, the device will remain paused.

Upon completion, PauseOnly stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the PauseOnly method has completed. The Notify property determines whether PauseOnly generates an OnNotify event.


TMediaPlayer::Play

TMediaPlayer	See also 	Example

Plays the media loaded in the open multimedia device.

void __fastcall Play(void);

Description

Play is called when the Play button on the media player control is clicked at runtime.

Upon completion, Play stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Play method has completed. The Notify property determines whether Play generates an OnNotify event.

If the StartPos property is set, playing starts at the position specified in StartPos. Otherwise, playing starts at the current position, specified in the Position property. Similarly, if the EndPos property is set, playing stops at the position specified in EndPos. Otherwise, playing stops at the end of the medium.

Whether the medium (specified in the Position property) is rewound before playing starts depends on the AutoRewind property.


TMediaPlayer::Previous

TMediaPlayer	See also 	Example

Sets the current position to the beginning of the previous track if the position was at the beginning of a track when Previous was called.

void __fastcall Previous(void);

Description

If the position is at the first track or somewhere other than the beginning of a track when Previous was called, Previous sets the current position to the beginning of the current track. If the device doesn't use tracks, Previous sets the current position to the beginning of the medium, which is specified in the Start property. Previous is called when the Previous button on the media player control is clicked at runtime.

Upon completion, Previous stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Previous method has completed. The Notify property determines whether Previous generates an OnNotify event.


TMediaPlayer::Resume

TMediaPlayer	See also

Resumes playing or recording the currently paused multimedia device.

void __fastcall Resume(void);

Description

Resume is called when the Pause button on the media player control is clicked at runtime, when the device is paused.

Upon completion, Resume stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Resume method has completed. The Notify property determines whether Resume generates an OnNotify event.


TMediaPlayer::Rewind

TMediaPlayer	See also 	Example

Sets the current position to the beginning of the the medium, which is stored in the Start property.

void __fastcall Rewind(void);

Description

Upon completion, Rewind stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Rewind method has completed. The Notify property determines whether Rewind generates an OnNotify event.


TMediaPlayer::Save

TMediaPlayer	See also

Saves the currently loaded medium to the file specified in the FileName property.

void __fastcall Save(void);

Description

Save is ignored for devices that don't use media stored in files (video discs, for example).

Upon completion, Save stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Save method has completed. The Notify property determines whether Save generates an OnNotify event.


TMediaPlayer::StartRecording

TMediaPlayer	See also

Begins recording from the current Position or from the position specified in StartPos.

void __fastcall StartRecording(void);

Description

StartRecording is called when the Record button on the media player control is clicked at runtime.

Upon completion, StartRecording stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the StartRecording method has completed. The Notify property determines whether StartRecording generates an OnNotify event.

By default, the Notify property becomes true, and the Wait property becomes false upon completion of the StartRecording method. However, if these properties have been set to specific values prior to calling StartRecording, they remain unchanged.


TMediaPlayer::Step

TMediaPlayer	See also

Moves forward a number of frames (determined by the Frames property) in the currently loaded medium.

void __fastcall Step(void);

Description

Step is called when the Step button on the media player control is clicked at runtime.

Upon completion, Step stores a numerical error code in the Error property and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Step method has completed. The Notify property determines whether Step generates an OnNotify event.


TMediaPlayer::Stop

TMediaPlayer	See also

Halts playing or recording.

void __fastcall Stop(void);

Description

Stop is called when the Stop button on the media player control is clicked at runtimeruntime.

Upon completion, Stop stores a numerical error code in the Error property, and the corresponding error message in the ErrorMessage property.

The Wait property determines whether control is returned to the application before the Stop method has completed. The Notify property determines whether Stop generates an OnNotify event.


TMediaPlayer::Updated

TMediaPlayer	See also

Signals that the media player has finished updating.

DYNAMIC void __fastcall Updated(void);

Description

Updated calls the parent class's Updated before it modifies the layout of the media player buttons forces a repaint.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


TMemIniFile

Hierarchy	Properties	Methods	See also

TMemIniFile is a low-level wrapper for the 16-bit Windows 3.x INI file system that enables storage and retrieval of application-specific information and settings in an application-specific INI file.

Unit

inifiles

Description

Use TMemIniFile to storage and retrieve application-specific information and settings in a Windows 3.x INI file. The INI file text format is the standard way for Windows 3.x applications to store and retrieve application settings from session to session. An INI file stores information in logical groupings, called “sections::” For example, the WIN.INI file contains a section called “[Desktop]”. Within each section, actual data values are stored in named keys. Keys take the form:

Unlike the TIniFile object, which also acts as a gateway to INI file data, TMemIniFile buffers all changes to the INI file. The INI file the TMemIniFile uses is read once, when the object is first created. Data from the INI file is stored in nested TString objects. Each section in the INI file occupies one element in the top-most TStrings object, and each element in this TStrings may itself contain a TStrings object. Each element in each of the contained TStrings object represent a key within the section. After the data is read, any changes to the data are stored in memory in these nested TStrings objects. A method is provided to write the data from memory to the associated INI file.

All TMemIniFile methods to read, write, and erase sections, keys, and values operate on the in-memory copy of the INI file.

This buffering of INI file data is important under the Windows NT environment, where INI file writes are not buffered. In applications where there is a significant amount of reading from or writing to an INI file, this buffering prevents degradation of the application’s performance.

The FileName passed to a TIniFile object when it is created is the name of the INI file the object accesses. Because the data is written to the INI file by C++Builder, and not the operating system, the saving of data changes is faster in all supported versions of Windows.

TMemIniFile provides a property and methods for reading from and writing to specific INI files, and for deleting entire sections in an INI file. In addition to these properties and methods, TMemIniFile inherits the methods of TCustomIniFile and TObject.

Note:

TMemIniFile is supported only for migration purposes and backward compatibility. 32-bit Windows replaces INI files with a system registry where all applications store and retrieve their settings. Applications that target 32-bit Windows should use the system registry instead of INI files. C++Builder provides objects for handling the system registry, such as TRegistry. TRegistryIniFile also encapsulates the registry, but provides an easier migration path for existing Windows 3.1 applications that are upgraded 32-bit Windows.


TMemIniFile properties

TMemIniFile	Alphabetically	Legend

Derived from TCustomIniFile

FileName


TMemIniFile properties

TMemIniFile	By object	Legend

FileName


TMemIniFile methods

TMemIniFile	Alphabetically

In TMemIniFile

~TMemIniFile

Clear

DeleteKey

EraseSection

GetStrings

ReadSection

ReadSections

ReadSectionValues

ReadString

Rename

SetStrings

TMemIniFile

UpdateFile

WriteString

Derived from TCustomIniFile

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadTime

SectionExists

ValueExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteTime

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMemIniFile methods

TMemIniFile	By object

~TMemIniFile

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DeleteKey

Dispatch

EraseSection

FieldAddress

Free

FreeInstance

GetStrings

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

Rename

SectionExists

TMemIniFile

UpdateFile

ValueExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime


TMemIniFile::Clear

TMemIniFile	See also

Erases all data from the INI file in memory.

void __fastcall Clear(void);

Description

Call Clear to erase all data from the INI file that is currently buffered in memory. All sections, keys, and values are erased. No exception is generated when using Clear and the data has not been saved to the INI file with the UpdateFile method.


TMemIniFile::TMemIniFile

TMemIniFile	See also 	Example

Creates a TMemIniFile object for an application.

__fastcall TMemIniFile(const System::AnsiString FileName);

Description

Call TMemIniFile to construct a TMemIniFile object for an application. TMemIniFile inherits TMemIniFile from TCustomIniFile, and creates an additional property, FileName, which is used to specify the name of the INI file to use. TMemIniFile also loads a copy of the INI file into memory, in an internal TStrings object.

FileName is the name of the INI file the TMemIniFile uses.

Note:

Usually INI files are stored in the \WINDOWS directory. To work with an INI file in another location, specify the full path name of the file in FileName.


TMemIniFile::DeleteKey
 KTMemIniFile::DeleteKey

TMemIniFile	See also 	Example

Erases the data value associated with an INI file entry.

virtual void __fastcall DeleteKey(const System::AnsiString Section, const System::AnsiString Ident);

Description

Call DeleteKey to erase a data value associated with an INI file entry. Section is string containing the name of an INI file section, and Ident is a string containing the name of the key from for which to set a NULL value.

Note:	Attempting to erase a data value in a non-existent section or attempting to erase data from a non-existent key are not errors. In these cases, DeleteKey creates the section and key and sets its initial value to an empty value.

DeleteKey only affects the in-memory copy of the INI file, not the copy on disk.


TMemIniFile::EraseSection

TMemIniFile	See also

Erases an entire section of an INI file.

virtual void __fastcall EraseSection(const System::AnsiString Section);

Description

Call EraseSection to remove a section, all its keys, and their data values from an INI file. Section identifies the INI file section to remove. If a section cannot be removed, an exception is raised.

EraseSection only affects the in-memory copy of the INI file, not the copy on disk.


TMemIniFile::GetStrings

TMemIniFile	See also

Populates a string list with INI file data.

void __fastcall GetStrings(Classes::TStrings* List);

Description

Call GetStrings to copy the INI file data currently stored in memory into a pre-existing string list.

List is a string list object, created and maintained by the application, into which the INI file data is copied.


TMemIniFile::ReadSection
 KTMemIniFile::ReadSection

TMemIniFile	See also

Reads all the key names from a specified section of an INI file into a string list.

virtual void __fastcall ReadSection(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSection to retrieve the names of all keys within a specified section of an INI file into a string list object.

Section identifies the section from which to retrieve a list of key names. Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object such as a string list, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.

Data read by ReadSection comes from the in-memory copy of the INI file, not the copy on disk.


TMemIniFile::ReadSections

TMemIniFile	See also

Reads the names of all sections in an INI file into a string list.

virtual void __fastcall ReadSections(Classes::TStrings* Strings);

Description

Call ReadSections to retrieve the names of all sections in an INI file into a string list object.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.

Data read by ReadSections comes from the in-memory copy of the INI file, not the copy on disk.


TMemIniFile::ReadSectionValues

TMemIniFile	See also

Reads the values from all keys within a section of an INI file into a string list.

virtual void __fastcall ReadSectionValues(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSectionValues to read the values from all keys within a specified section of an INI file into a string list object. Section identifies the section in the file from which to read key values. Strings is the string list object into which to read the values.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.

Data read by ReadValues comes from the in-memory copy of the INI file, not the copy on disk.


TMemIniFile::ReadString

TMemIniFile	See also 	Example

Retrieves a string value from an INI file.

virtual System::AnsiString __fastcall ReadString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Default);

Description

Call ReadString to read a string value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the value. Default is the string value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.

The ReadString method inherited from TCustomIniFile is modified to operate on the in-memory copy of the INI file data. The read methods for all other data types is effected internally by ReadString and then translated to the appropriate data type.


TMemIniFile::Rename

TMemIniFile	See also

Associates the TMemIniFile with a different INI file.

void __fastcall Rename(const System::AnsiString FileName, bool Reload);

Description

Call Rename to change the INI file used by the TMemIniFile object to a file other than the one specified when the object was created.

FileName is name of the new INI file to use.

Reload determines whether data is immediately loaded into memory from the INI file specified in FileName.


TMemIniFile::SetStrings

TMemIniFile	See also

Populates the memory buffer with contents of a string list.

void __fastcall SetStrings(Classes::TStrings* List);

Description

Call UpdateFile to populate the in-memory copy of the INI file data with the contents of a string list.

List is a string list object, created and maintained by the application, from which the INI file data is copied.

SetStrings uses the Clear method to erase any existing INI file data prior to copying the new data.

SetStrings can be used to reread data from the INI file from disk after it is erased with the Clear method. The LoadFromFile method of a string list can be used to retrieve the contents of the INI file and SetStrings to copy the data into the memory buffer for TMemIniFile.


TMemIniFile::UpdateFile

TMemIniFile	See also

Flushes buffered INI file data to disk.

virtual void __fastcall UpdateFile(void);

Description

Call UpdateFile to copy INI file data stored in memory to the copy of the INI file on disk. UpdateFile is useful under Windows95, but has no effect under Windows NT as NT does not buffer INI file reads and writes.

UpdateFile overwrites all data in the disk copy of the INI file with the INI file data stored in memory.

If the Rename method is used to change the INI file the TMemIniFile uses, UpdateFile copies the INI file data in memory to a file of the new name. If the file does not already exist, it is created. If the new file already exists, it is overwritten.


TMemIniFile::WriteString

TMemIniFile	See also 	Example

Writes a string value to an INI file.

virtual void __fastcall WriteString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Value);

Description

Call WriteString to write a string value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the string value to write.

The WriteString method inherited from TCustomIniFile is modified to operate on the in-memory copy of the INI file data. The write methods for all other data types is effected internally by WriteString after data values are translated from the original data type.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteString creates the section and key and sets its initial value to Value.


TMemIniFile::~TMemIniFile

TMemIniFile

~TMemIniFile frees the memory associated with the TMemIniFile object.

__fastcall virtual ~TMemIniFile(void);

Description

Do not call ~TMemIniFile directly. Instead, use the delete keyword on the object, which causes ~TMemIniFile to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TCustomIniFile


 TMemo

Hierarchy	Properties	Methods	Events	See also

TMemo is a wrapper for a windows multiline edit control.

Unit

stdctrls

Description

Use TMemo to put a standard Windows multiline edit control on a form. Multiline edit boxes allow the user to enter more than one line of text. They are appropriate for representing lengthy information.

TMemo implements the generic behavior introduced in TCustomMemo. TMemo publishes many of the properties inherited from TCustomMemo, but does not introduce any new behavior.


TMemo properties

TMemo	Alphabetically	Legend

Derived from TCustomMemo

Alignment

CaretPos

Lines

ScrollBars

WantReturns

WantTabs

WordWrap

Derived from TCustomEdit

CanUndo

BorderStyle

HideSelection

MaxLength

Modified

OEMConvert

ReadOnly

SelLength

SelStart

SelText

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TMemo properties

TMemo	By object	Legend

Align

Alignment

BorderStyle

BoundsRect

Brush

CanUndo

CaretPos

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

HideSelection

Hint

ImeMode

ImeName

Left

Lines

MaxLength

Modified

Name

OEMConvert

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

ScrollBars

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

WantReturns

WantTabs

Width

WindowProc

WordWrap


TMemo events

TMemo	Alphabetically	Legend

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TMemo events

TMemo	By object	Legend

OnChange

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TMemo methods

TMemo	Alphabetically

In TMemo

~TMemo

TMemo

Derived from TCustomEdit

Clear

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

GetSelTextBuf

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMemo methods

TMemo	By object

~TMemo

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TMemo

Undo

Update

UpdateControlState


TMemo::TMemo

TMemo

Creates a new TMemo object.

__fastcall virtual TMemo(Classes::TComponent* AOwner) : Stdctrls::TCustomMemo(AOwner) { }

__fastcall TMemo(HWND ParentWindow) : Stdctrls::TCustomMemo(ParentWindow) { }

Description

Do not call TMemo directly when creating a memo at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TMemo object. Memos placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the TMemo object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the memo in a non-VCL window. This syntax is used when the memo is implemented as an ActiveX control that is embedded in a non-VCL window.


TMemo::~TMemo

TMemo

Frees the memory associated with the TMemo object.

__fastcall virtual ~TMemo(void) { }

Description

Do not call ~TMemo directly. Instead, use the delete keyword on the object, which causes ~TMemo to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMemo


TMemoField

Hierarchy	Properties	Methods	Events	See also

TMemoField represents a memo field in a dataset.

Unit

db

Description

Memo fields are a form of binary large object (BLOB) field where the data consists of an arbitrarily large string of text. TMemoField differs from its immediate ancestor TBlobField only in the value of the DataType property. As a descendent of TBlobField, TMemoField includes many properties, methods, and events that are useful for managing the value and properties of a BLOB field in a database.


TMemoField properties

TMemoField	Alphabetically	Legend

Derived from TBlobField

AsString

AsVariant

BlobSize

BlobType

IsNull

Modified

Transliterate

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TMemoField properties

TMemoField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

BlobSize

BlobType

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

HasConstraints

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Modified

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

Transliterate

ValidChars

Value

VCLComObject

Visible


TMemoField events

TMemoField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TMemoField events

TMemoField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TMemoField methods

TMemoField	Alphabetically

In TMemoField

~TMemoField

TMemoField

Derived from TBlobField

Assign

Clear

IsBlob

LoadFromFile

LoadFromStream

SaveToFile

SaveToStream

SetFieldType

SetText

Derived from TField

AssignValue

FocusControl

GetData

IsValidChar

RefreshLookupList

SetData

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMemoField methods

TMemoField	By object

~TMemoField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SaveToFile

SaveToStream

SetData

SetFieldType

SetText

TMemoField

Validate


TMemoField::TMemoField

TMemoField	See also

Creates an instance of TMemoField.

__fastcall virtual TMemoField(Classes::TComponent* AOwner);

Description

Do not call TMemoField directly. To instantiate a TMemoField object at runtime, use the new keyword. TMemoField objects placed on forms or data modules at design time are created automatically.

After calling the parent class’s constructor, TMemoField sets the DataType to ftMemo, and initializes the Transliterate property to true.


TMemoField::~TMemoField

TMemoField

~TMemoField frees the memory associated with the TMemoField object.

__fastcall virtual ~TMemoField(void) { }

Description

Do not call ~TMemoField directly. Instead, use the delete keyword on the object, which causes ~TMemoField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TBlobField


TMemoryStream

Hierarchy	Properties	Methods	See also

TMemoryStream is a stream that stores its data in dynamic memory.

Unit

classes

Description

Use TMemoryStream to store data in a dynamic memory buffer that is enhanced with file-like access capabilities. TMemoryStream provides the general I/O capabilities of a stream object while introducing methods and properties to manage a dynamic memory buffer.

Memory streams are useful as intermediary objects that can hold information as well as read it from or write it to another storage medium. They provide a useful format for comparing the contents of streams, or for manipulating data that is stored in a less accessible medium.


TMemoryStream properties

TMemoryStream	Alphabetically	Legend

Derived from TCustomMemoryStream

Memory

Derived from TStream

Position

Size


TMemoryStream properties

TMemoryStream	By object	Legend

Memory

Position

Size


TMemoryStream methods

TMemoryStream	Alphabetically

In TMemoryStream

~TMemoryStream

Clear

LoadFromFile

LoadFromStream

SetSize

TMemoryStream

Write

Derived from TCustomMemoryStream

Read

SaveToFile

SaveToStream

Seek

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TMemoryStream methods

TMemoryStream	By object

~TMemoryStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

SaveToFile

SaveToStream

Seek

SetSize

TMemoryStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TMemoryStream::Clear

TMemoryStream	See also

Frees the memory buffer, discarding all data associated with the memory stream.

void __fastcall Clear(void);

Description

Use Clear to empty the memory buffer for the memory stream and free all associated memory. In addition to freeing the memory associated with the memory buffer, Clear

•	Sets the Memory property to NULL.

•	Sets the Position property to 0.

•	Sets the Size property to 0.


TMemoryStream::~TMemoryStream

TMemoryStream	See also

Destroys an instance of TMemoryStream.

__fastcall virtual ~TMemoryStream(void);

Description

Do not call ~TMemoryStream directly in an application. Instead, use the delete keyword.

Delete a TMemoryStream object when it is no longer needed to store or write data. ~TMemoryStream calls Clear to free the memory buffer before calling the parent class’s destructor.


TMemoryStream::LoadFromFile

TMemoryStream	See also

Loads the entire contents of a file into the memory buffer.

void __fastcall LoadFromFile(const System::AnsiString FileName);

Description

Use LoadFromFile to fill the memory stream with the contents of a file. Pass the name of the file as the FileName parameter. LoadFromFile allows an application to read the contents of a file into the memory stream without having to explicitly create and free a file stream object.

LoadFromFile reallocates the memory buffer so that the contents of the file will exactly fit. It sets the Size property accordingly, and then reads the entire contents of the file into the memory buffer. Thus, LoadFromFile will discard any pre-existing data stored in the memory stream.


TMemoryStream::LoadFromStream

TMemoryStream	See also

Loads the entire contents of a stream into the memory buffer.

void __fastcall LoadFromStream(TStream* Stream);

Description

Use LoadFromStream to fill the memory stream with the contents of the stream specified by the Stream parameter. LoadFromStream always sets the Position of the source stream to 0, before streaming in the number of bytes indicated by the source stream’s Size property.

LoadFromStream reallocates the memory buffer so that the contents of the source stream will exactly fit. It sets the Size property accordingly, and then reads the entire contents of the source stream into the memory buffer. Thus, LoadFromStream will discard any pre-existing data stored in the memory stream.

If the source stream is a TFileStream object, LoadFromStream does the same thing as LoadFromFile, except that the application must create and free the TFileStream object. LoadFromStream also allows applications to fill a memory stream object from other types of stream objects.


TMemoryStream::SetSize

TMemoryStream	See also

Sets the Size property of the memory stream.

virtual void __fastcall SetSize(int NewSize);

Description

Use SetSize to set the Size of a memory stream before filling it with data. SetSize allocates the memory buffer to hold NewSize bytes, preserving as much of the existing data as possible.

Use SetSize before filling the memory buffer with data from various sources, or from a portion of another stream. If the intended contents of the memory stream is exactly the same as the contents of another stream or file, use LoadFromStream or LoadFromFile instead.


TMemoryStream::Write

TMemoryStream	See also

Writes Count bytes from Buffer to the current position in the memory buffer and updates the current position by Count bytes.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Use Write to insert Count bytes into the memory buffer of the memory stream, starting at the current position. Write will increase the size of the memory buffer, if necessary, to accommodate the data being written in. If the current position is not the end of the memory buffer, Write will overwrite the data following the current position.

Write updates the Size property to Position + Count, and sets the Position property to the new value of Size. Thus, any data that was stored in the memory stream in the Count bytes after the current position is lost when calling Write.

Write always writes the Count bytes in the Buffer, unless there is a memory failure. Thus, for TMemoryStream, Write is equivalent to the WriteBuffer method.

All other data-writing methods of a memory stream (WriteBuffer, WriteComponent) call Write to do the actual writing.


TMemoryStream::TMemoryStream

TMemoryStream

Creates a new TMemoryStream object.

__fastcall TMemoryStream(void) : Classes::TCustomMemoryStream() { }

Description

Do not call TMemoryStream directly in an application. Instead, use the new keyword, to obtain an indirect reference to a newly created memory stream.


Accessibility

Read-only


Hierarchy

TObject

TStream

TCustomMemoryStream


TMenu

Hierarchy	Properties	Methods	See also

TMenu is the base type for menu components such as TMainMenu and TPopupMenu.

Unit

menus

Description

Use TMenu as a base class when defining a component that represents a collection of menu items. TMenu introduces properties and methods to create a Windows menu that represents a set of menu items, dispatch commands associated with those menu items, and locate the help context id for any of those menu items.


TMenu properties

TMenu	Alphabetically	Legend

In TMenu

Handle

Items

WindowHandle

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TMenu properties

TMenu	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Handle

Items

Name

Owner

Tag

VCLComObject

WindowHandle


TMenu::Handle

TMenu	See also

Provides access to the Windows menu handle for the menu.

__property HMENU Handle = {read=GetHandle, nodefault};

Description

Use Handle to call a Windows API function that requires a menu handle. Handle is the handle for the menu that contains only the items described by the Items property. If no other menus have been merged with this menu, this is the same as the WindowHandle property.


TMenu::Items

TMenu	See also

Describes the elements of the menu.

__property TMenuItem* Items = {read=FItems};

Description

Use Items to access information about the elements in the menu. Items is a single TMenuItem object that describes the elements of the menu in its own Items property.

FirstItem := Menu1->Items->Items[0];

Set the Items property at design time by clicking on the Items property in the Property Inspector. The Menu Designer automatically inserts a menu item. As each menu item is entered, outlined regions appear at the possible locations of additional menu items. Click in those regions to specify additional menu items. At runtime, create a TMenuItem that describes the elements of the menu programmatically, and set the Items property of the menu.


TMenu::WindowHandle

TMenu	See also

Provides access to the handle of the window that uses the menu.

__property HWND WindowHandle = {read=FWindowHandle, write=SetWindowHandle, nodefault};

Description

Read WindowHandle to get the window handle of the control that receives WM_COMMAND messages when the user clicks on an item in the menu. When menu items are selected, use this handle in an OnClick event handler to send messages to the control that uses the menu or to make Windows API calls that affect the control.

Set WindowHandle to associate the menu with a control.


TMenu methods

TMenu	Alphabetically

In TMenu

~TMenu

DispatchCommand

DispatchPopup

FindItem

GetHelpContext

IsShortCut

TMenu

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMenu methods

TMenu	By object

~TMenu

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

DispatchCommand

DispatchPopup

FieldAddress

FindComponent

FindItem

Free

FreeInstance

FreeNotification

FreeOnRelease

GetHelpContext

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsShortCut

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TMenu


TMenu::TMenu

TMenu	See also

Creates an instance of TMenu.

__fastcall virtual TMenu(Classes::TComponent* AOwner);

Description

Call TMenu indirectly, using the new keyword to create a menu control at runtime. Menus placed on forms at design time are created automatically. TMenu sets the initial values for the menu component, including creating an Items property.

Pass a single Component as a parameter to provide the TMenuItem object with an Owner that is responsible for freeing it.


TMenu::~TMenu

TMenu	See also

Destroys the menu component.

__fastcall virtual ~TMenu(void);

Description

Do not call ~TMenu directly in an application. Instead, use the delete keyword on the object, which causes ~TMenu to be invoked automatically.


TMenu::DispatchCommand

TMenu	See also

Calls the Click method of the menu item with the specified value as its Command property.

bool __fastcall DispatchCommand(Word ACommand);

Description

Call DispatchCommand to simulate a click on the menu item associated with a command ID. If DispatchCommand locates a menu item that matches the command ID, it calls the Click method for that menu item and returns true. If there is no such item, DispatchCommand returns false.


TMenu::DispatchPopup

TMenu	See also

Dispatches a pop-up menu command.

bool __fastcall DispatchPopup(HMENU AHandle);

Description

Call DispatchPopup to simulate a click on the menu item associated with the pop-up menu handle. If DispatchPopup locates a menu item that matches the pop-up menu handle, it calls the Click method for that menu item and returns true. If there is no such item, DispatchPopup returns false.


TMenu::FindItem

TMenu	See also

Locates and returns a menu item.

TMenuItem* __fastcall FindItem(int Value, TFindItemKind Kind);

Description

Call FindItem to locate a menu item in the menu or one of its submenus. The menu item is identified by either a pop-up menu handle, command ID, or menu shortcut value. The Kind parameter specifies how the menu item is to be identified. It can be any of these values:

Value	Meaning

fkCommand	Command ID used by Windows WM_COMMAND message matches the Value parameter.

fkHandle	Pop-up menu handle matches the Value parameter.

fkShortCut	Menu shortcut key code matches the Value parameter.


TMenu::GetHelpContext

TMenu	See also

Returns the help context ID associated with a menu item.

Classes::THelpContext __fastcall GetHelpContext(int Value, bool ByCommand);

Description

Call GetHelpContext to obtain the ID for context-sensitive help on a particular menu item. Identify the menu item as the item that matches the Value property. If ByCommand is true, Value is the Command property of the TMenuItem. If ByCommand is false, Value is the Handle property.


TMenu::IsShortCut

TMenu	See also

Dispatches a key message if it represents a shortcut key for an item in the menu.

bool __fastcall IsShortCut(Messages::TWMKey &Message);

Description

Call IsShortCut when processing a keydown message to identify shortcut keys and trigger the appropriate menu action. IsShortCut decodes the key message passed in the Message parameter. It then encodes the state of the Shift, Control, and Alt keys with the value of the character that was typed to obtain the ShortCut property of a menu item. If IsShortCut locates a menu item associated with the shortcut key combination, it calls the item's Click method and returns true. If no item in the menu has a shortcut corresponding to the message, IsShortCut returns false.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent


TMenuItem

Hierarchy	Properties	Methods	Events	See also

TMenuItem describes the properties of an item in a menu.

Unit

menus

Description

Use TMenuItem to specify the appearance and behavior of an item in a menu. Each TMainMenu or TPopupMenu component can contain multiple menu items. When a menu is defined at design time, the Menu Designer automatically creates menu item objects for each command on the menu.


TMenuItem properties

TMenuItem	Alphabetically	Legend

In TMenuItem

Break

Caption

Checked

Command

Count

Default

Enabled

GroupIndex

Handle

HelpContext

Hint

Items

MenuIndex

Parent

RadioItem

ShortCut

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TMenuItem properties

TMenuItem	By object	Legend

Break

Caption

Checked

Command

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Count

Default

DesignInfo

Enabled

GroupIndex

Handle

HelpContext

Hint

Items

MenuIndex

Name

Owner

Parent

RadioItem

ShortCut

Tag

VCLComObject

Visible


TMenuItem::Break

TMenuItem	See also

Determines whether the menu item starts a new column in the menu.

__property TMenuBreak Break = {read=FBreak, write=SetBreak, default=0};

Description

Set Break to break a long menu into columns at the item described by this menu item. These are the possible values:

Value	Meaning

mbNone	No menu breaking occurs. This is the default value.

mbBarBreak	The Parent menu breaks into another column with the menu item appearing at the top of the new column. A bar separates the new and the old columns.

mbBreak	The Parent menu breaks into another column with the menu item appearing at the top of the new column. Only space separates the new and the old columns.


TMenuItem::Caption

TMenuItem	See also 	Example

Specifies the text of the menu item.

__property System::AnsiString Caption = {read=FCaption, write=SetCaption};

Description

Set Caption to the string the user sees for this item in the menu. To underline a character in a string, include an ampersand (&) before the character. This type of character is called an accelerator character. If Caption includes an accelerator character, the user can select the menu item by pressing Alt while typing the underlined character.

Use the Caption property to identify the menu item as a line that separates the menu into parts. Specify a hyphen character (-) as the value of Caption for the menu item to indicate that the menu item is a separator. To separate the menu into multiple columns, use the Break property instead.


TMenuItem::Checked

TMenuItem	See also	Example

Specifies whether a check mark should appear beside the Caption.

__property bool Checked = {read=FChecked, write=SetChecked, default=0};

Description

Use Checked to allow a menu item to work like a check box. If Checked is true, the menu item appears checked. If Checked is false, the menu item remains unchecked.


TMenuItem::Command

TMenuItem	See also 	Example

Specifies the Windows command ID associated with the menu item.

__property Word Command = {read=FCommand, nodefault};

Description

Use Command in an application that directly handles WM_COMMAND messages. When the user selects the menu item, Windows sends a WM_COMMAND to the window associated with the menu. The ItemID of the message contains the value of the Command property of the menu item that was selected.


TMenuItem::Count

TMenuItem	See also 	Example

Indicates the number of subitems of the menu item.

__property int Count = {read=GetCount, nodefault};

Description

Read Count to determine the number of subitems listed in the Items property array. When the user clicks on a menu item that has subitems, a dropdown menu appears which displays those subitems. Each subitem can, in turn, contain additional subitems. The Count property counts only the immediate subitems of the menu item.


TMenuItem::Default

TMenuItem	See also

Specifies whether the menu item is invoked when the parent item is double clicked.

__property TMenuItem* Items[int Index] = {read=GetItem};

Description

Set Default to specify whether a menu item is the default item in a submenu. Default menu items are executed when the parent item is double-clicked, allowing users to avoid navigating the submenus that contain them.

The default item appears in boldface. A submenu can have only one default item. If the Items list of the parent menu item already contains a default menu item, setting the Default property to true sets the Default property of the previous default item to false.

Note:	The Default property works under Windows NT 3::51 only if the “new shell” has been installed.


TMenuItem::Enabled

TMenuItem	See also 	Example

Specifies whether the menu item is enabled.

__property bool Enabled = {read=FEnabled, write=SetEnabled, default=1};

Description

Use Enabled to enable or disable a menu item. If Enabled is true, the Click method is called when the user selects the item with the mouse. If Enabled is false, the menu item appears dimmed and the user cannot select it.

Note:	Calling the Click method works even when Enabled is false.


TMenuItem::GroupIndex

TMenuItem	See also

Identifies the logical group to which the menu item belongs.

__property Byte GroupIndex = {read=FGroupIndex, write=SetGroupIndex, default=0};

Description

Use GroupIndex to control how menus are merged. In applications that contain multiple forms, items from the menus of secondary forms can be merged into the application’s main menu as those forms become active. MDI applications always merge the menus of child windows with the main menu of the parent window.

By default, all menu items in a menu bar (main menu) have the same GroupIndex value. To use GroupIndex to merge menus, set the GroupIndex value of each successive menu item to a value equal to or greater than that of the previous menu item.

When a menu item in a menu bar that is merged into the application’s main menu has the same GroupIndex value as a menu item in the main menu, the menu item in the application’s main menu is replaced by the corresponding menu item. If multiple menu items in the application’s main menu have the same GroupIndex value, they can be replaced only by separate menu items from the other form’s menu that also have repeated GroupIndex values. Thus, the first main menu item with a given value is replaced by the first item in the second form with that value, the second item in the main form is replaced by the second item in the second form, and so on.

When a menu item in a menu bar that is merged into the application’s main menu has a GroupIndex that falls between the GroupIndex values of two adjacent items on the application’s main menu, that menu item is inserted between the two adjacent items. If the item’s GroupIndex value is greater than all other GroupIndex values in the application’s main menu, the item appears at the end of the main menu. If the GroupIndex value is less than all other GroupIndex values in the application’s main menu, the menu item appears at the beginning of the main menu bar.

When an object created by an OLE 2::0 server application is activated, the server can try to merge its menus with the menus of the container application. The GroupIndex property is used to replace up to three main menu items with items from the server, in the manner described above. The server application uses the following predefined GroupIndex values to locate menu items to replace:

Group	Index	Description

Edit	1	Server menu items for editing the active OLE object

View	3	Server menu items for modifying the view of the OLE object.

Help	5	Server menu items for accessing the server’s online Help.

Note:	 See the documentation for the OLE server for information about whether it attempts menu merge during in-place activation.

GroupIndex can also be used to define groups of menu items that act like radio buttons. To allow menu items to behave like radio buttons, set the RadioItem property to all menu items in the group to true, and assign each menu item the same value of GroupIndex. Checking any menu item in the group will then uncheck the others.


TMenuItem::Handle

TMenuItem	See also

Indicates the Windows menu handle of the drop-down menu associated with the menu item.

__property HMENU Handle = {read=GetHandle, nodefault};

Description

Use Handle when calling a Windows API function that requires a menu handle. Handle is only valid if the Count property is greater than 0.


TMenuItem::HelpContext

TMenuItem	See also

Specifies the help context ID associated with the menu item.

__property Classes::THelpContext HelpContext = {read=FHelpContext, write=FHelpContext, default=0};

Description

Use HelpContext to associate the menu item with a screen in the Help system of the application. Each screen in the Help system should have a unique context ID. When a menu item is selected using the keyboard, pressing F1 displays a Help screen. Which Help screen appears depends on the value of the HelpContext property.


TMenuItem::Hint

TMenuItem	See also

Specifies the text string that can appear when the user moves the mouse pointer over a menu item.

__property System::AnsiString Hint = {read=FHint, write=FHint};

Description

Set Hint to a string that provides more information about the meaning of the menu item than the Caption. The hint text appears in a Help Hint window when the user pauses with the mouse over the menu item if Help Hints are enabled. It is also available for the code in the application’s OnHint event handler.

The value of Hint can specify both a short value for the Help Hint window and a longer string to be used by the OnHint event handler. To provide both a short and a long hint, set Hint to the short string, followed by a vertical bar (|), followed by the long string.


TMenuItem::Items

TMenuItem	See also 	Example

Lists the menu items in the submenu of the menu item.

__property TMenuItem* Items[int Index] = {read=GetItem};

Description

Use Items to access to a subitem by its position in the list of subitems. The value of Index is the position of the subitem within the Items array. For example, if an application has a File drop-down menu that contains the menu items New, Open, and Save, in that order, FileMenu::Items[2] refers to the Save command.


TMenuItem::MenuIndex

TMenuItem	See also

Indicates the index of the menu item within its parent menu.

__property int MenuIndex = {read=GetMenuIndex, write=SetMenuIndex, nodefault};

Description

Use MenuIndex to locate the menu item in the Items property of its parent menu item. Changing this value moves the menu item within its menu.

Note:	MenuIndex may not correspond to the position of the item in the menu the user sees. The menu can include items that are not visible.


TMenuItem::Parent

TMenuItem	See also

Identifies the parent menu item of this menu item.

__property TMenuItem* Parent = {read=FParent};

Description

Read Parent to determine the menu item that represents the dropdown menu that contains this menu item. If the menu item is a top level menu item in a main menu or pop-up menu, Parent is the value of that menu’s Items property.


TMenuItem::RadioItem

TMenuItem	See also

Specifies whether the menu item is mutually exclusive with other menu items in its group.

__property bool RadioItem = {read=FRadioItem, write=SetRadioItem, default=0};

Description

Use RadioItem to make the menu item behave like a radio button with a group of other menu items. When RadioItem is true, only one menu item in the group that contains the menu item can be selected at a time. The group of menu items is the set of all menu items in a pop-up or drop-down menu that have the same value of GroupIndex. The single selected menu item in the group is indicated by a round dot next to the Caption.

RadioItem does not work for the top-level items in a main menu.

Note:	Under Windows NT 3::51, the round dot indicator only appears if the “new shell” has been installed.


TMenuItem::ShortCut

TMenuItem	See also

Specifies the key combination users can type to quickly access the menu item.

__property TShortCut ShortCut = {read=FShortCut, write=SetShortCut, default=0};

Description

Use ShortCut to allow the user to type a key combination instead of selecting the item using the menu. This key combination appears to the right of the menu item in the menu.

When setting menu shortcuts at design time, the Object Inspector provides a long list of key combinations to choose from. To create menu shortcuts at runtime, use the global ShortCut or TextToShortCut function. For example, the following line creates a shortcut, Ctrl+C and assigns it to a menu item named CloseCommand.


TMenuItem::Visible

TMenuItem	See also

Specifies whether the menu item appears in the menu.

__property bool Visible = {read=FVisible, write=SetVisible, default=1};

Description

Use Visible to prevent the user from seeing an item in the menu. For example, remove menu items that do not apply to the current component of a pop-up menu in an OnPopup event handler.

If Visible is true, the menu item appears. If Visible is false, the menu item is hidden.


TMenuItem events

TMenuItem	Alphabetically	Legend

In TMenuItem

OnClick


TMenuItem events

TMenuItem	By object	Legend

OnClick


TMenuItem::OnClick

TMenuItem	See also 	Example

Occurs when the user clicks menu item.

__property Classes::TNotifyEvent OnClick = {read=FOnClick, write=FOnClick};

Description

Write an OnClick event handler to implement the desired behavior for when the user selects the menu item. An advantage of using the OnClick event handler over directly handling WM_COMMAND messages sent when the user selects the menu item, is that only the OnClick event occurs when the Click method is called.


TMenuItem methods

TMenuItem	Alphabetically

In TMenuItem

~TMenuItem

Add

Click

Delete

IndexOf

Insert

Remove

TMenuItem

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMenuItem methods

TMenuItem	By object

~TMenuItem

Add

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

DefaultHandler

Delete

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

IndexOf

InheritsFrom

InitInstance

Insert

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Remove

RemoveComponent

SafeCallException

TMenuItem


TMenuItem.Add

TMenuItem	See also 	Example

Adds a menu item to the end of the Items property array.

void __fastcall Add(TMenuItem* Item);

Description

Use Add to add a new menu item to the dropdown menu for this menu item. If this menu item is the value of the Items property of a main menu or pop-up menu, Add adds an item to the end of the menu. Specify the new menu item to add as the value of the Item parameter.


TMenuItem::Click

TMenuItem	See also

Simulates a mouse click.

virtual void __fastcall Click(void);

Description

Click generates an OnClick event, as if the user had clicked the menu item. Unlike a real mouse click, Click does not generate a WM_COMMAND message to the window associated with the menu.

Component writers can override click to provide a different response when the user selects the menu item.


TMenuItem::TMenuItem

TMenuItem	See also 	Example

Creates an instance of TMenuItem.

__fastcall virtual TMenu(Classes::TComponent* AOwner);

Description

Call TMenuItem indirectly, using the new keyword to create a menu item control at runtime.

Menu items defined at design time using the Menu designer are created automatically. After calling the parent object’s constructor, TMenuItem initializes the Visible and Enabled properties to true, and generates a unique value for the Command property.

Pass a single Component as a parameter to provide the TMenuItem object with an Owner that is responsible for freeing it.


TMenuItem::Delete

TMenuItem	See also

Removes a menu item from the Items property array.

void __fastcall Delete(int Index);

Description

Call Delete to remove a menu item and all its submenus from a menu. The Index parameter is the index of the item to be deleted, where 0 specifies the first item in the menu, 1 specifies the second item, and so on.

To temporarily hide a menu item, without deleting it, use the Visible property.


TMenuItem::~TMenuItem

TMenuItem	See also

Destroys an instance of TMenuItem.

__fastcall virtual ~TMenuItem(void);

Description

Do not call ~TMenuItem directly in an application. Instead, use the delete keyword on the object, which causes ~TMenuItem to be invoked automatically.


TMenuItem::IndexOf

TMenuItem	See also

Returns the position of a menu item within the Items array.

int __fastcall IndexOf(TMenuItem* Item);

Description

Call IndexOf to locate a menu item in the submenu headed by this menu item. IndexOf returns 0 for the first menu item, 1 for the second menu item, and so on. If the menu item is not in the submenu, IndexOf returns -1.

Note:	IndexOf may not correspond to the position of the item in the menu the user sees if the menu includes some items that are not visible.


TMenuItem::Insert

TMenuItem	See also 	Example

Inserts a menu item into a specified position in the Items array.

HIDESBASE void __fastcall Insert(int Index, TMenuItem* Item);

Description

Use Insert to insert a new menu item to the dropdown menu for this menu item. If this menu item is the value of the Items property of a main menu or pop-up menu, Insert inserts an item into that menu. Specify the new menu item to add as the value of the Item parameter, and the position in the Items array as the value of the Index parameter.


TMenuItem::Remove

TMenuItem	See also

Removes a menu item from the Items property array

HIDESBASE void __fastcall Remove(TMenuItem* Item);

Description

Call Remove to remove a menu item and all its submenus from a menu. The Item parameter is the item to be removed. If Item is not a menu item in the Items array, Remove raises an exception.

To temporarily hide a menu item, without deleting it, use the Visible property.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


TMetafile

Hierarchy	Properties	Methods	Events	See also

TMetafile is an encapsulation of the Win32 Enhanced metafile.

Unit

graphics

Description

TMetafile contains a metafile graphic (EMF file format).

Properties of TMetafile indicate the size and characteristics of the metafile.

To draw a metafile on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing a TMetafile as a parameter. The Enhanced property determines how the metafile will be stored on disk. If Enhanced is true, the metafile is stored as an EMF (Win32 Enhanced Metafile) file. If Enhanced is false, the metafile is stored as a WMF (Windows 3.1 Metafile, with Aldus header).


TMetafile properties

TMetafile	Alphabetically	Legend

In TMetafile

CreatedBy

Description

Empty

Enhanced

Handle

Height

Inch

MMHeight

MMWidth

Palette

Width

Derived from TGraphic

Modified

PaletteModified

Transparent


TMetafile properties

TMetafile	By object	Legend

CreatedBy

Description

Empty

Enhanced

Handle

Height

Inch

MMHeight

MMWidth

Modified

Palette

PaletteModified

Transparent

Width


TMetafile::TMetafile
TMetafile::CreatedBy

TMetafile	See also

Specifies the name of the author or application used to create the metafile.

__property System::AnsiString CreatedBy = {read=GetAuthor};

Description

Use CreatedBy to set the string to an optional name of the author or application used to create the metafile. To set the CreatedBy string of a new metafile, call the CreateWithComment method of TMetafileCanvas.


TMetafile::Description

TMetafile	See also

Provides an optional text description that is embedded in the metafile.

__property System::AnsiString Description = {read=GetDesc};

Description

Set the Description string of a new metafile by calling the CreateWithComment method of TMetafileCanvas.


TMetafile::Empty

TMetafile	Example

Specifies whether the metafile object contains a metafile.

__property bool Empty = {read=GetEmpty, nodefault};

Description

Empty is true if no metafile has been loaded into the metafile object and false if the metafile object contains a metafile.


TMetafile::Enhanced

TMetafile

Determines how the metafile will be stored on disk.

__property bool Enhanced = {read=FEnhanced, write=FEnhanced, default=1};

Description

Use Enhanced to determine how the metafile is stored on disk. If Enhanced is true, the metafile is stored as an .EMF (Win32 Enhanced Metafile). If Enhanced is false, the metafile is stored as a .WMF (Windows 3.1 Metafile, with Aldus header).

The in-memory format is always EMF. WMF has very limited capabilities; storing as WMF will lose information that would be retained by EMF. This property is set to match the metafile type when loaded from a stream or file. If loaded as WMF, then save as WMF.


TMetafile::Handle

TMetafile 	See also

Provides access to the Windows GDI metafile handle, for accessing the GDI metafile object.

__property int Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

Use Handle when calling a Windows API function that requires the handle of a metafile object. Pass the handle from the Handle property of the metafile object to the function.


TMetafile::Height

TMetafile	See also

Specifies the vertical size in pixels of the metafile.

__property int Height = {read=GetHeight, nodefault};

Description

Use Height to find or set the vertical height of the metafile.


TMetafile::Inch

TMetafile

Returns the units per inch that are used for the metafile's coordinate mapping.

__property Word Inch = {read=GetInch, write=SetInch, nodefault};

Description

Use Inch to find the units per inch assumed by a WMF metafile, and to alter scale when writing as WMF, but otherwise this property is obsolete. Enhanced metafiles maintain complete scale information internally. For example, if the metafile was created in a Twips coordinate system (using MM_TWIPS mapping), the value of Inch is 1440.


TMetafile::MMHeight

TMetafile	See also

Contains the height of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles.

__property int MMHeight = {read=GetMMHeight, write=SetMMHeight, nodefault};

Description

MMHeight is used for a more accurate reading of the vertical size of the graphic. The Height property, by contrast, is always in screen device pixel units; to avoid loss of precision in converting between device pixels and millimeters, set or read the dimensions in millimeters with MMHeight.


TMetafile::MMWidth

TMetafile	See also

Contains the width of the metafile image in 0.01 millimeter units, the native scale used by enhanced metafiles.

__property int MMWidth = {read=GetMMWidth, write=SetMMWidth, nodefault};

Description

MMWidth is used for a more accurate reading of the horizontal size of the graphic. The Width property, by contrast, is always in screen device pixel units; to avoid loss of precision in converting between device pixels and millimeters, set or read the dimensions in millimeters with MMWidth.

The MMWidth property is always in screen device pixel units.


TMetafile::Palette

TMetafile

Controls a metafile's color mapping.

__property HPALETTE Palette = {read=GetPalette, write=SetPalette, nodefault};

Description

Use Palette to assign custom palettes created with the Windows API CreatePalette function to this property.

The Palette of a metafile contains up to 256 colors that can be used to display the metafile on screen. When running in a 256-color video mode, and if the metafile is drawn by an application running in the foreground, all colors of Palette are added to the Windows system palette. If the metafile is drawn by an application running in the background and another application has loaded the system palette with its own colors, the metafile's colors are mapped to the system palette. Palette=0 if the metafile has no palette.


TMetafile::Width

TMetafile	See also

Specifies the horizontal size in pixels of the metafile.

__property int Width = {read=GetWidth, write=SetWidth, nodefault};

Description

Use Width to find the horizontal size in pixels of the metafile.


TMetafile events

TMetafile	Alphabetically

Derived from TGraphic

OnChange

OnProgress


TMetafile events

TMetafile	By object

OnChange

OnProgress


TMetafile methods

TMetafile	Alphabetically

In TMetafile

~TMetafile

Assign

Clear

LoadFromClipboardFormat

LoadFromStream

ReleaseHandle

SaveToClipboardFormat

SaveToFile

SaveToStream

TMetafile

Derived from TGraphic

LoadFromFile

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TMetafile methods

TMetafile	By object

~TMetafile

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromClipboardFormat

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

ReleaseHandle

SafeCallException

SaveToClipboardFormat

SaveToFile

SaveToStream

TMetafile


TMetafile::Assign

TMetafile	See also

Copies an object to the metafile.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the Enhanced and Palette properties of an object to the metafile. If the metafile is NULL, Assign creates one. Otherwise, Assign calls the parent class's method. For assignment, metafiles are polymorphic with other TGraphic objects, and with TPicture.


TMetafile::Clear

TMetafile	See also

Deletes the metafile image.

void __fastcall Clear(void);

Description

Use Clear to release the old metafile image, create a new image, and increment a reference count on it.


TMetafile::TMetafile

TMetafile	See also	Example

Instantiates a metafile object.

__fastcall virtual TMetafile(void);

Description

Call TMetafile indirectly using the new keyword to instantiate a metafile at runtime.

TMetafile allocates memory for a metafile object, and calls the parent object’s constructor. Then sets the Enhanced and Transparent properties to true.

To create a metafile image from scratch, draw the image in a metafile canvas.  When the metafile canvas is destroyed, it transfers the image into the metafile object provided to the metafile canvas constructor. After the image is drawn on the canvas and the canvas is destroyed, the image is 'playable' in the metafile object.


TMetafile::~TMetafile

TMetafile	See also

Destroys an instance of a metafile object.

__fastcall virtual ~TMetafile(void);

Description

Do not call ~TMetafile directly in an application. Instead, an application should call delete.

~TMetafile releases the image, which frees the image and the handle when the reference count on the metafile image is zero. Then ~TMetafile calls the parent object’s destructor.


TMetafile::LoadFromClipboardFormat

TMetafile	See also

Loads a metafile from the Clipboard.

virtual void __fastcall LoadFromClipboardFormat(Word AFormat, int AData, HPALETTE APalette);

Description

LoadFromClipboardFormat replaces the current image with the data pointed to by the AData parameter. The palette for the metafile is specified by the APalette parameter. LoadFromClipboardFormat is called if the metafile is registered with the TPicture object using the RegisterClipboardFormat method.


TMetafile::LoadFromStream

TMetafile	See also

Loads the metafile from a stream.

virtual void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Use LoadFromStream by specifying the stream from which the metafile is loaded as the value of Stream. LoadFromStream reads a metafile from a stream and replaces the current image with it.


TMetafile::ReleaseHandle

TMetafile	See also

Releases the Windows GDI object represented by the metafile.

int __fastcall ReleaseHandle(void);

Description

Call ReleaseHandle to release the resources used to represent the metafile. ReleaseHandle sets the Handle property to NULL.

Call ReleaseHandle before setting the Handle property, so that the resources associated with the metafile are not lost.


TMetafile::SaveToClipboardFormat

TMetafile	See also

Saves a metafile to a Clipboard format.

virtual void __fastcall SaveToClipboardFormat(Word &AFormat, int &AData, HPALETTE &APalette);

Description

Use SaveToClipboardFormat by specifying the palette as the value of the APalette parameter, the format as the value of AFormat, and data to be saved as the value of AData. Before the metafile can be saved, an application must have registered the format with the metafile object using the RegisterClipboardFormat method.

To save a metafile to a file, call SaveToFile.


TMetafile::SaveToFile

TMetafile	See also

Writes the metafile to disk.

virtual void __fastcall SaveToFile(const System::AnsiString Filename);

Description

Use SaveToFile to save the metafile to a file provided by the Filename parameter. To load a metafile from a file, call the LoadFromFile method.


TMetafile::SaveToStream

TMetafile	See also

Writes the metafile to a stream.

virtual void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Use SaveToStream to save the metafile to the stream specified by the value of the Stream parameter.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TGraphic


TMetaClass

See also	Example

Header

vcl/sysdefs.h

class PACKAGE TMetaClass;

typedef TMetaClass* TClass;

Description

TMetaClass is the C++Builder representation of the Delphi class-reference type. The TMetaClass for a given class can be acquired by using the __classid keyword keyword.

TMetaClass allows operations to be performed directly on classes. This contrasts with class types (that are instantiated as objects), which allow operations to be performed on instances of classes.

A variable of type TMetaClass can be null, which indicates that the variable does not currently reference a class.

Every class inherits (from TObject) a method function called ClassType, which returns a reference to the class of an object. The type of the value returned by ClassType is TClass (TMetaClass*), which is declared as class of TObject.

The methods of TMetaClass correspond to the static methods of TObject. They have the same functionality but differ in parameters. Whereas the TObject methods take a TClass (TMetaClass*) as the first parameter, this parameter is implicit in the TMetaClass methods.


TMasterDataLink

Hierarchy	Properties	Methods	Events	See also

TMasterDataLink allows a dataset to obtain its records from another data source.

Unit

dbcommon

Description

Use TMasterDataLink as a private member of a dataset object that can represent the detail records for another dataset. TMasterDataLink maintains a list of field components from the master dataset, and passes on data events to the data source that owns it. In the constructor of the dataset that uses TMasterDataLink to link to another data source, create the TMasterDataLink object and set any event handlers to respond to data events.

Do not confuse the dataset that is the value of the DataSet property of TMasterDataLink with the dataset that uses TMasterDataLink to link to a master dataset. The DataSet property is the master dataset, while the dataset that owns the TMasterDataLink object is the detail set.

TClientDataSet and TTable objects already include a TMasterDataLink object.


TMasterDataLink properties

TMasterDataLink	Alphabetically	Legend

In TMasterDataLink

FieldNames

Fields

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TMasterDataLink properties

TMasterDataLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

FieldNames

Fields

ReadOnly

RecordCount


TMasterDataLink::FieldNames

TMasterDataLink	See also

Contains the names of fields from the data source that are represented by the dataset that owns the TMasterDataLink object.

__property System::AnsiString FieldNames = {read=FFieldNames, write=SetFieldNames};

Description

Set FieldNames to the fields that the dataset which owns the TMasterDataLink object should represent. Each field name in the string must be separated from other field names with a semicolon.

Setting FieldNames causes TMasterDataLink to regenerate the Fields property from the field components of the source dataset. Once the Fields property has been regenerated, TMasterDatalink triggers an OnMasterChange event.


TMasterDataLink::Fields

TMasterDataLink	See also

Lists all the field components from the data source that are used by the dataset that owns the TMasterDataLink.

__property Classes::TList* Fields = {read=FFields};

Description

Use Fields to access individual field components from the source data set. Fields provides the values for the Fields property of the dataset that owns the TMasterDataLink.

Fields is a read-only property. Fields is generated by locating the field components referenced by the FieldNames property in the source dataset.


TMasterDataLink events

TMasterDataLink	Alphabetically

In TMasterDataLink

OnMasterChange

OnMasterDisable


TMasterDataLink events

TMasterDataLink	By object

OnMasterChange

OnMasterDisable


TMasterDataLink::OnMasterChange

TMasterDataLink	See also

Occurs after the Fields property changes.

__property Classes::TNotifyEvent OnMasterChange = {read=FOnMasterChange, write=FOnMasterChange};

Description

Write an OnMasterChange event handler to update the dataset that owns the TMasterSourceLink to reflect any changes that occurred in the source dataset or the FieldNames property. The Fields property reflects the new state of the source dataset and the FieldNames property. If FieldNames refers to any fields that disappeared from the source dataset, the Fields property contains undefined field components for those fields.


TMasterDataLink::OnMasterDisable

TMasterDataLink	See also

Occurs when the source dataset becomes inactive.

__property Classes::TNotifyEvent OnMasterDisable = {read=FOnMasterDisable, write=FOnMasterDisable};

Description

Write an OnMasterDisable event handler to respond when the source dataset that provides the data for the dataset which owns the TMasterDataLink becomes inactive. When the source dataset is inactive, the field components in the Fields property can not be used to obtain the data from records in the source dataset. Thus, only information cached by the dataset which owns the TMasterDataLink can be used after OnMasterDisable until the next OnMasterChange event occurs.


TMasterDataLink methods

TMasterDataLink	Alphabetically	Legend

In TMasterDataLink

~TMasterDataLink

ActiveChanged

CheckBrowseMode

LayoutChanged

RecordChanged

TMasterDataLink

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TMasterDataLink methods

TMasterDataLink	By object	Legend

~TMasterDataLink

ActiveChanged

Assign

CheckBrowseMode

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Edit

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LayoutChanged

MethodAddress

MethodName

NewInstance

RecordChanged

SafeCallException

TMasterDataLink

UpdateRecord


TMasterDataLink::ActiveChanged

TMasterDataLink	See also

Regenerates the Fields property and triggers an OnMasterChange or OnMasterDisable event.

virtual void __fastcall ActiveChanged(void);

Description

Applications can not call the ActiveChanged procedure directly. Changes in the Active property trigger this procedure. When the source dataset becomes inactive, ActiveChanged empties the Fields property and generates an OnMasterDisable event. When the dataset becomes active, ActiveChanged regenerates Fields from the source dataset and generates an OnMasterChange event.


TMasterDataLink::CheckBrowseMode

TMasterDataLink	See also

Informs the dataset that owns the TMasterDataLink object when the current record in the source dataset is about to change.

virtual void __fastcall CheckBrowseMode(void);

Description

Applications can not call the CheckBrowseMode procedure directly. CheckBrowseMode is called immediately before the current record in the source dataset changes. It calls the CheckBrowseMode method of the dataset that owns the TMasterDataLink object, so that it can post any pending edits before the record changes.


TMasterDataLink::TMasterDataLink

TMasterDataLink	See also

Creates an instance of TMasterDataLink.

__fastcall TMasterDataLink(Db::TDataSet* DataSet);

Description

Call TMasterDataLink indirectly, using the new keyword, from the constructor of the dataset that uses TMasterDataLink to link to a secondary data source. The dataset that uses the TMasterDataLink passes itself as the DataSet parameter.

TMasterDataLink associates the instance of TMasterDataLink with the dataset that owns it, and creates the helper objects it uses to manage the list of field components.


TMasterDataLink::~TMasterDataLink

TMasterDataLink	See also

Destroys an instance of TMasterDataLink.

__fastcall virtual ~TMasterDataLink(void);

Description

Do not call ~TMasterDataLink directly in an application. Instead, use the delete keyword to destroy the TMasterDataLink object from the destructor of the dataset that owns it.

~TMasterDataLink frees up the memory used to manage the list of field components.


TMasterDataLink::LayoutChanged

TMasterDataLink	See also

Informs the dataset that owns the TMasterDataLink object after the data source has changed the number of records buffered.

virtual void __fastcall LayoutChanged(void);

Description

Applications can not call the LayoutChanged method directly. LayoutChanged is called automatically when the source dataset changes to reflect a change in the layout of a control linked to that source dataset. LayoutChanged regenerates the Fields property and triggers an OnMasterChange event.


TMasterDataLink::RecordChanged

TMasterDataLink	See also

Generates an OnMasterChange event when the contents of one of the fields in the current record changes.

virtual void __fastcall RecordChanged(Db::TField* Field);

Description

Applications can not call RecordChanged directly. It is called automatically when the contents of the current record change. The Field parameter indicates which field in the current record has changed. If Field is NULL, the entire record has changed.

If the Field parameter is NULL, or if the Field parameter is one of the fields listed in the Fields property, RecordChanged triggers an OnMasterChange event.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


TMetaFileCanvas

Hierarchy	Properties	Methods	Events	See also

TMetafileCanvas allows applications to create metafile images from scratch.

Unit

graphics

Description

Use TMetafileCanvas as a surface on which to draw a metafile image. When the canvas is destroyed, it transfers the image into the metafile object provided to the canvas constructor. After the image is drawn on the canvas and the canvas is destroyed, the image is 'playable' in the metafile object.


TMetaFileCanvas properties

TMetaFileCanvas	Alphabetically	Legend

Derived from TCanvas

Brush

ClipRect

CopyMode

Font

Handle

LockCount

Pen

PenPos

Pixels


TMetaFileCanvas properties

TMetaFileCanvas	By object	Legend

Brush

ClipRect

CopyMode

Font

Handle

LockCount

Pen

PenPos

Pixels


TMetaFileCanvas events

TMetaFileCanvas	Alphabetically

Derived from TCanvas

OnChange

OnChanging


TMetaFileCanvas events

TMetaFileCanvas	By object

OnChange

OnChanging


TMetaFileCanvas methods

TMetaFileCanvas	Alphabetically

In TMetaFileCanvas

~TMetaFileCanvas

TMetaFileCanvas

Derived from TCanvas

Arc

BrushCopy

Chord

CopyRect

Draw

DrawFocusRect

Ellipse

FillRect

FloodFill

FrameRect

LineTo

Lock

MoveTo

Pie

PolyBezier

PolyBezierTo

Polygon

Polyline

Rectangle

Refresh

RoundRect

StretchDraw

TextExtent

TextHeight

TextOut

TextRect

TextWidth

Unlock

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TMetaFileCanvas methods

TMetaFileCanvas	By object

~TMetaFileCanvas

Arc

Assign

BrushCopy

Chord

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyRect

DefaultHandler

Dispatch

Draw

DrawFocusRect

Ellipse

FieldAddress

FillRect

FloodFill

FrameRect

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LineTo

Lock

MethodAddress

MethodName

MoveTo

NewInstance

Pie

PolyBezier

PolyBezierTo

Polygon

Polyline

Rectangle

Refresh

RoundRect

SafeCallException

StretchDraw

TextExtent

TextHeight

TextOut

TextRect

TextWidth

TMetaFileCanvas

Unlock


TMetafileCanvas::TMetaFileCanvas

TMetafileCanvas	See also	Example

Creates an instance of TMetafileCanvas and acquires a handle to a metafile device context.

__fastcall TMetafileCanvas(TMetafile* AMetafile, HDC ReferenceDevice);

__fastcall TMetafileCanvas(TMetafile* AMetafile, HDC ReferenceDevice, const System::AnsiString CreatedBy, const System::AnsiString Description);

Description

Do not call TMetaFileCanvas directly. Instead, use the new keyword, which returns an indirect reference to a newly instantiated metafile canvas. Pass in the metafile that uses the canvas as the AMetafile parameter. Pass in a handle to a device context on which to base the metafile’s device context as the ReferenceDevice parameter. In most cases, this is the device context for a window on which the image is normally drawn.  To create a metafile canvas for a metafile that has a Description strings, use the second constructor syntax, passing a string describing the creator of the metafile as CreatedBy and further descriptive text as Description.

TMetaFileCanvas sets the size of the TMetafile object from the HDC passed as ReferenceDevice if it does not already have the MMHeight and MMWidth properties set. If the second syntax is used, the CreatedBy and Description strings are used to create a description for the metafile. TMetaFileCanvas then creates a metafile device context, and sets the Handle property to its handle. All subsequent drawing methods will draw to the metafile device context.

When the TMetaFileCanvas is destroyed, the handle of AMetafile is set to the metafile canvas’s Handle, and the CreatedBy and Description strings are used to set the properties of the same name in the TMetafile object.


TMetaFileCanvas::~TMetaFileCanvas

TMetafileCanvas	See also

Destroys an instance of the TMetafileCanvas after transferring the image to the TMetaFile object that was passed to the constructor.

__fastcall virtual ~TMetafileCanvas(void);

Description

Do not call Destroy directly in an application. Instead, use the delete keyword.

Destroy sets the Handle property of the TMetaFile object that was passed to the constructor before freeing the memory associated with the object.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCanvas


TMetafileImage

Hierarchy	Methods	See also

TMetafileImage is the internal representation of the metafile image for a TMetafile object.

Unit

graphics

Description

TMetafileImage is used for internal implementation only in C++Builder. It represents the internal image of the metafile encapsulated by the TMetafile object. All of the data and methods introduced in TMetafileImage are private. They contain information about the specific metafile image, including pointers to the standard HENHMETAFILE (enhanced metafile handle) and HPALETTE (handle to palette) structures defined by Windows.


TMetafileImage methods

TMetafileImage	Alphabetically

In TMetafileImage

~TMetafileImage

TMetafileImage

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TMetafileImage methods

TMetafileImage	By object

~TMetafileImage

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TMetafileImage


TMetafileImage::~TMetafileImage

TMetafileImage	See also

Disposes of the instance of a metafile image.

__fastcall virtual ~TMetafileImage(void);

Description

Do not call ~TMetafileImage directly in an application. Instead, an application should call delete.

~TMetafileImage frees the metafile handle and palette before calling the parent object’s destructor.


TMetafileImage::TMetafileImage

TMetafileImage

Creates a new TMetafileImage object.

__fastcall virtual ~TMetafileImage(void);

Description

Call TMetafileImage indirectly, using the new keyword.


Hierarchy

TObject

TSharedImage


TMetafileImage example

TMetafileImage


 TMIDASConnection

Hierarchy	Properties	Methods	Events	See also

TMIDASConnection handles a remote server connection in a client application that is part of a multi-tiered application.

Unit

MIDASCon

Description

TMIDASConnection is used in the client portion of a multi-tiered database application to establish and maintain the connection between the client and a remote application server. TMIDASConnection objects can

•	Establish an initial connection to a remote application server using DCOM, TCP/IP sockets, or OLEnterprise.

•	Provide a list of provider names available to client datasets through this connection.

•	Obtain an IProvider interface based on a provider name.

•	Maintain a list of local client datasets that can be serviced through this connection.

•	Drop the connection to the remote application server.

The MIDAS connection object establishes the initial connection between the client application and a remote application server using DCOM, TCP/IP sockets, or OLEnterprise. Once the connection is established, the client registers any or all of its client datasets with the remote server, and these client datasets can then communicate directly with the application server’s TProvider object through its IProvider interface.

Note:	TMIDASConnection depends on objects in both the VCLDB30.DPL and INET30.DPL packages.  If the client application will only be using DCOM to connect to the application server, the dependancy on INET30.DPL can be removed by using TRemoteServer instead.

Note:	See the EMPEDIT and MSTRDTL demos for examples of how to use TMIDASConnection.


TMIDASConnection properties

TMIDASConnection	Alphabetically	Legend

In TMIDASConnection

ConnectType

ServerPort

UseBroker

Derived from TRemoteServer

AppServer

ComputerName

Connected

ServerGUID

ServerName

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TMIDASConnection properties

TMIDASConnection	By object	Legend

AppServer

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ComputerName

Connected

ConnectType

DesignInfo

Name

Owner

ServerGUID

ServerName

ServerPort

Tag

UseBroker

VCLComObject


TMIDASConnection::ConnectType

TMIDASConnection	See also

Specifies the protocol to use to establish the connection to the application server.

enum TConnectType { ctDCOM, ctSockets, ctOLEnterprise };

__property TConnectType ConnectType = {read=FConnectType, write=SetConnectType, nodefault};

Description

Use ConnectType to specify the desired protocol for connecting with the application server.  If ConnectType is ctDCOM, the TMIDASConnection component uses DCOM to establish the connection.  Communication with the application server uses the DCOM IProvider interface returned by the GetProvider method.  When establishing a connection using DCOM, the ServerName property specifies the GUID of the application server and the ComputerName property specifies the name of the server machine.

Note:	Not all Windows95 machines support DCOM.  If the capabilities of the client environment are not known, use the ctSockets connect type.

If ConnectType is ctSockets, the TMIDASConnection component establishes the connection to the application server using TCP/IP sockets and connects to a socket dispatcher component on the application server.  Communication with the application server uses the IProvider interface, which is passed over the socket connection via an IDispatch interface. When establishing a connection using TCP/IP, the ServerPort specifies the Port property of the socket dispatcher used by the application server and the ComputerName property specifies the host name or IP address of the server application.

If ConnectType is ctOLEnterprise, the TMIDASConnection component establishes the connection using OLE enterprise, which must be installed on the client machine. Communication with the application server uses the IPRovider interface returned by the GetProvider method.  When establishing a connection using OLEnterprise, the ComputerName property specifies either the name of the server machine or the name of the OLEnterprise Business Object Broker, depending on the value of the UseBroker property.


TMIDASConnection::ServerPort

TMIDASConnection	See also

Specifies the port number used by the application server when listening for TCP/IP connections.

__property int ServerPort = {read=FServerPort, write=FServerPort, default=211};

Description

When establishing connections to the application server using TCP/IP sockets, the application server must have a socket dispatcher listening on a predefined port for requests from client applications.  If the value of ConnectType is ctSockets, set ServerPort to the value of the Port property of the socket dispatcher on the application server.  The TMIDASConnection component will attempt to establish a connection to the application server by sending a message to the system specified by the ComputerName property at the port specified by ServerPort.

Note:	ServerPort has no effect if ConnectType is not ctSockets.


TMIDASConnection::UseBroker

TMIDASConnection	See also

Indicates whether an OLEnterprise connection should use the OLEnterprise Business Object Broker.

__property bool UseBroker = {read=FUseBroker, write=SetUseBroker, nodefault};

Description

When establishing connections to the application server using OLEnterprise, UseBroker specifies whether the connection should use the Business Object Broker.  If UseBroker is true, the TMIDASConnection uses the Business Object Broker, and the ComputerName property specifies the name of the Business Object Broker.  If UseBroker is false, the TMIDASConnection uses OLEnterprise, but does not go through the Business Object Broker.  When UseBroker is false, ComputerName specifies the name of the OLEnterprise server.

For more information about using OLEnterprise, see the OLEnterprise documentation.

Note:	The value of UseBroker has no effect unless ConnectType is ctOLEnterprise.


TMIDASConnection events

TMIDASConnection	Alphabetically	Legend

Derived from TCustomRemoteServer

AfterConnect

AfterDisconnect

BeforeConnect

BeforeDisconnect


TMIDASConnection events

TMIDASConnection	By object	Legend

AfterConnect

AfterDisconnect

BeforeConnect

BeforeDisconnect


TMIDASConnection methods

TMIDASConnection	Alphabetically

In TMIDASConnection

~TMIDASConnection

TMIDASConnection

Derived from TRemoteServer

GetProvider

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TMIDASConnection methods

TMIDASConnection	By object

~TMIDASConnection

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetProvider

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TMIDASConnection


TMIDASConnection::TMIDASConnection

TMIDASConnection	See also

Creates and initializes an instance of TMIDASConnection.

__fastcall virtual TMIDASConnection(Classes::TComponent* AOwner);

Description

Call TMIDASConnection indirectly, using the new keyword, to instantiate a TMIDASConnection component at runtime.  TMIDASConnection components placed in forms or data modules at design time are created automatically.

TMIDASConnection initializes the value of the ServerPort property to 211.  This is also the default port number for the TSocketDispatcher component.


TMIDASConnection::~TMIDASConnection

TMIDASConnection	See also

Disposes of an instance of TMIDASConnection.

__fastcall virtual ~TMIDASConnection(void);

Description

Do not call ~TMIDASConnection directly in an application.  Instead, use the delete keyword.

If the ConnectType property is ctSockets, ~TMIDASConnection ensures that the socket connection is closed before destroying the TMIDASConnection component.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomRemoteServer

TRemoteServer


TNamedItem

Hierarchy	Properties	Methods	See also

TNamedItem is the base class for definitions used by datasets.

Unit

db

Description

Use TNamedItem as a base class when defining a class of definition that is maintained in a collection by a dataset.  Sets of TNamedItem objects are maintained by a descendant of TDefCollection that is specific to the type of object defined.

Definition objects are used by datasets to specify the properties of database entities such as fields or indexes.


TNamedItem properties

TNamedItem	Alphabetically	Legend

In TNamedItem

DisplayName

Name

Derived from TCollectionItem

Collection

ID

Index


TNamedItem properties

TNamedItem	By object	Legend

Collection

DisplayName

ID

Index

Name


TNamedItem::DisplayName

TNamedItem	See also

Specifies the name of the named item as it appears in the collection editor at design time.

__property System::AnsiString DisplayName = {read=GetDisplayName};

Description

TNamedItem overrides the DisplayName property to ensure that its value is the same as the value of the Name property. Thus, the name that appears in the collection editor is the same as the name of the defined database entity as it appears (or will appear) in the dataset.


TNamedItem::Name

TNamedItem	See also 	Example

Specifies the name of the database entity defined by the TNamedItem object.

__property System::AnsiString Name = {read=FName, write=SetDisplayName};

Description

Use Name to specify the name that the underlying database table uses to refer to the defined object. For example, if the TNamedItem object is a field definition, the value of Name is the name of the corresponding field in the underlying database table.

Note:	For dBASE maintained indexes, Name refers to the tag name of the index. For Paradox tables, the Name of the primary key is an empty string.


TNamedItem methods

TNamedItem	Alphabetically

In TNamedItem

~TNamedItem

TNamedItem

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TNamedItem methods

TNamedItem	By object

~TNamedItem

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TNamedItem


TNamedItem::TNamedItem

TNamedItem

Creates a new TNamedItem object.

__fastcall virtual TNamedItem(Classes::TCollection* Collection) : Classes::TCollectionItem(Collection) { }

Description

Do not create instances of TNamedItem. Instead, create instances of the appropriate descendant (such as TFieldDef or TIndexDef) using the new keyword.


TNamedItem::~TNamedItem

TNamedItem

~TNamedItem frees the memory associated with the TNamedItem object.

__fastcall virtual ~TNamedItem(void) { }

Description

Do not call ~TNamedItem directly. Instead, use the delete keyword on the object, which causes ~TNamedItem to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


TNavDataLink

Hierarchy	Properties	Methods	See also

TNavDataLink helps manage the link to the dataset for a TDBNavigator object.

Unit

dbctrls

Description

TNavDataLink is tailored to work with a TDBNavigator. It should only be used by the TDBNavigator class.


TNavDataLink properties

TNavDataLink	Alphabetically	Legend

Derived from TDataLink

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TNavDataLink properties

TNavDataLink	By object	Legend

Active

ActiveRecord

BufferCount

DataSet

DataSource

DataSourceFixed

Editing

ReadOnly

RecordCount


TNavDataLink methods

TNavDataLink	Alphabetically	Legend

In TNavDataLink

~TNavDataLink

ActiveChanged

DataSetChanged

EditingChanged

TNavDataLink

Derived from TDataLink

Edit

UpdateRecord

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TNavDataLink methods

TNavDataLink	By object	Legend

~TNavDataLink

ActiveChanged

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DataSetChanged

DefaultHandler

Dispatch

Edit

EditingChanged

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TNavDataLink

UpdateRecord


TNavDataLink::ActiveChanged

TNavDataLink	See also

Informs TDBNavigator of changes in the Active property.

virtual void __fastcall ActiveChanged(void);

Description

Applications should not call the ActiveChanged procedure directly. Changes in the Active property trigger this procedure, which in turn causes the navigator to enable or disable its buttons, as appropriate.


TNavDataLink::TNavDataLink

TNavDataLink	See also

Creates an instance of TNavDataLink.

__fastcall TNavDataLink(TDBNavigator* ANav);

Description

Applications should not call the TNavDataLink method for a TNavDataLink directly. The TDBNavigator that owns a TNavDataLink creates it from its own constructor.


TNavDataLink::DataSetChanged

TNavDataLink	See also

Informs the TDBNavigator of changes to the dataset.

virtual void __fastcall DataSetChanged(void);

Description

Applications do not need to call the DataSetChanged procedure. It is called automatically following changes to the contents of the dataset. TNavDataLink informs the TDBNavigator of these changes so that it can enable and disable buttons as appropriate.


TNavDataLink::~TNavDataLink

TNavDataLink	See also

Destroys an instance of TNavDataLink.

__fastcall virtual ~TNavDataLink(void);

Description

Applications should not call the ~TNavDataLink method for a TNavDataLink directly. The TDBNavigator that owns a TNavDataLink destroys the TNavDataLink from its own destructor.


TNavDataLink::EditingChanged

TNavDataLink	See also

Informs TDBNavigator of changes to the editing state of the DataSource.

virtual void __fastcall EditingChanged(void);

Description

Applications should not call the EditingChanged procedure directly. Changes to the editing state of the DataSource trigger this procedure, which in turn causes the navigator to enable or disable editing buttons as appropriate.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TDataLink


TNumericField

Hierarchy	Properties	Methods	Events	See also

TNumericField is the common ancestor of all the numeric fields in a dataset.

Unit

db

Description

TNumericField is an abstract base class that encapsulates the fundamental behavior common to all numeric field components. In addition to the properties, events, and methods common to all field components introduced by TField, TNumericField introduces new properties for formatting numeric data for display or editing purposes.


TNumericField properties

TNumericField	Alphabetically	Legend

In TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Value

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TNumericField properties

TNumericField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TNumericField::DisplayFormat

TNumericField	See also

Determines how a numeric field’s value is formatted for display in a data-aware control.

__property System::AnsiString DisplayFormat = {read=FDisplayFormat, write=SetDisplayFormat};

Description

Use the DisplayFormat property to override automatic formatting of a field for display purposes.

The value of DisplayFormat is a string that encodes the formatting of numeric data using the specifiers in the following table:

Specifier	Represents

0	Digit placeholder. If the value being formatted has a digit in the position where the "0" appears in the format string, then that digit is copied to the output string. Otherwise, a "0" is stored in that position in the output string.

#	Digit placeholder. If the value being formatted has a digit in the position where the "#" appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.

.	Decimal point. The first "." character in the format string determines the location of the decimal separator in the formatted value; any additional "." characters are ignored. The actual character used as a the decimal separator in the output string is determined by the DecimalSeparator global variable. The default value of DecimalSeparator is specified in the Number Format of the Regional Settings section in the Windows Control Panel.

,	Thousand separator. If the format string contains one or more "," characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of "," characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is determined by the ThousandSeparator global variable. The default value of ThousandSeparator is specified in the Number Format of the Regional Settings section in the Windows Control Panel.

E+	Scientific notation. If any of the strings "E+", "E-", "e+", or "e-" are contained in the format string, the number is formatted using scientific notation. A group of up to four "0" characters can immediately follow the "E+", "E-", "e+", or "e-" to determine the minimum number of digits in the exponent. The "E+" and "e+" formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The "E-" and "e-" formats output a sign character only for negative exponents.

'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting.

;	Separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost "0" before the decimal point in the format string and the rightmost "0" after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ("0" or "#") to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the "." character in the format string, the extra digits are output before the first digit placeholder.

The following table shows the effect of various format strings:

DisplayFormat	Value	Result	Comment
#.##	12.2	12.2	Note extra digit to left of decimal still appears
#::00	2.5	2.50	Note extra zero: field will always show two decimal places
00.##	.006	00.01	Note extra 0s to right of decimal point and rounding to two decimal places.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

•	One section: The format string applies to all values.

•	Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

•	Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If the section for negative values or the section for zero values is empty, that is, if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

If the section for positive values is empty, or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.

Note:	DisplayFormat affects only the display of the field’s data. It does not affect the  validity of strings assigned to a numeric field using the AsString property.


TNumericField::EditFormat

TNumericField	See also

Determines how a numeric field’s value is formatted when it is being edited in a data-aware control.

__property System::AnsiString EditFormat = {read=FEditFormat, write=SetEditFormat};

Description

Use the EditFormat property to override the formatting of a field when the field’s value is being edited in a data-aware control.

When EditFormat is unassigned, but the DisplayFormat property has a value, the DisplayFormat string is used.

The value of EditFormat is a string that encodes the formatting of numeric data using the specifiers in the following table:

Specifier	Represents

0	Digit placeholder. If the value being formatted has a digit in the position where the "0" appears in the format string, then that digit is copied to the output string. Otherwise, a "0" is stored in that position in the output string.

#	Digit placeholder. If the value being formatted has a digit in the position where the "#" appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.

.	Decimal point. The first "." character in the format string determines the location of the decimal separator in the formatted value; any additional "." characters are ignored. The actual character used as a the decimal separator in the output string is determined by the DecimalSeparator global variable. The default value of DecimalSeparator is specified in the Number Format of the Regional Settings section in the Windows Control Panel.

,	Thousand separator. If the format string contains one or more "," characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of "," characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is determined by the ThousandSeparator global variable. The default value of ThousandSeparator is specified in the Number Format of the Regional Settings section in the Windows Control Panel.

E+	Scientific notation. If any of the strings "E+", "E-", "e+", or "e-" are contained in the format string, the number is formatted using scientific notation. A group of up to four "0" characters can immediately follow the "E+", "E-", "e+", or "e-" to determine the minimum number of digits in the exponent. The "E+" and "e+" formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The "E-" and "e-" formats output a sign character only for negative exponents.

'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting.

;	Separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost "0" before the decimal point in the format string and the rightmost "0" after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ("0" or "#") to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the "." character in the format string, the extra digits are output before the first digit placeholder.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

•	One section: The format string applies to all values.

•	Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

•	Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

If the section for positive values is empty, or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.

Note:	EditFormat affects only the display of the field’s data when it is being edited. It does not affect the validity of strings assigned to a numeric field using the AsString property, nor does it affect the display of the field’s data when it is not being edited.


TNumericField events

TNumericField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TNumericField events

TNumericField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TNumericField methods

TNumericField	Alphabetically

In TNumericField

~TNumericField

TNumericField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TNumericField methods

TNumericField	By object

~TNumericField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TNumericField

Validate


TNumericField::TNumericField

TNumericField	See also

Creates an instance of a TNumericField object.

__fastcall virtual TNumericField(Classes::TComponent* AOwner);

Description

Do not create instances of TNumericField. Instead, create an appropriate descendant of TNumericField using the new keyword.

After calling the parent class’s constructor, TNumericField changes the Alignment property to taRightJustify.


TNumericField::~TNumericField

TNumericField

~TNumericField frees the memory associated with the TNumericField object.

__fastcall virtual ~TNumericField(void) { }

Description

Do not call ~TNumericField directly. Instead, use the delete keyword on the object, which causes ~TNumericField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField


TObject

Methods	See also

TObject is the ultimate ancestor for all VCL objects and components.

Unit

system

Description

TObject encapsulates the fundamental behavior common to all objects in the VCL by introducing interfaces for methods that provide:

•	Class type and instance information on an object, and run-time type information (RTTI) about its published properties.

•	Support for message-handling.

Use TObject as an immediate base class when declaring simple objects that do not need to persist (are not saved and reloaded) and that do not need to be assigned to other objects.

Much of the powerful capability of C++Builder objects is established by the methods that TObject introduces. Many of these methods are used internally by the C++Builder environment and are not intended for users to call directly. Several others are generally overridden in descendant objects and components that have more complex behavior.

Note:	While TObject has no pure virtual methods, objects of this type are not normally instantiated.


TObject methods

TObject	Alphabetically

In TObject

~TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TObject


TObject methods

TObject	By object

~TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TObject


TObject::AfterConstruction

TObject	See also

Responds when the last constructor has executed.

virtual void __fastcall AfterConstruction();

Description

AfterConstruction is called automatically after the object’s last constructor has executed. Do not call it explicitly in your applications. The AfterConstruction method implemented in TObject does nothing. Override this method when creating a class that takes some action after the object is created. For example, TCustomForm overrides AfterConstruction to generate an OnCreate event.


TObject::BeforeDestruction

TObject	See also

Responds before the first destructor executes.

virtual void __fastcall BeforeDestruction();

Description

BeforeDestruction is called automatically immediately before the object’s first destructor executes. Do not call it explicitly in your applications. The BeforeDestruction method implemented in TObject does nothing. Override this method when creating a class that takes some action before the object is destroyed. For example, TCustomForm overrides BeforeDestruction to generate an OnDestroy event.


TObject::ClassInfo

TObject	See also

Returns a pointer to the run-time type information (RTTI) table for the object type.

typedef TMetaClass* TClass;

static void * __fastcall ClassInfo(TClass cls);

void * __fastcall ClassInfo(){return ClassInfo(ClassType()); }

Description

Use ClassInfo to access the RTTI table that contains information about the object type, its ancestor type, and all of its published properties:

•	Call ClassInfo with no arguments to obtain the RTTI table for a specific object instance.

•	Call the static TObject::ClassInfo method, passing the metaclass information, to obtain the RTTI table for a class of object when you don’t have an instance.

RTTI is used internally in the C++Builder environment. ClassInfo is rarely called directly in an application. TObject provides other methods specifically intended to provide easier access to RTTI information.


TObject::ClassName

TObject	See also	Example

Returns a string containing the name of the type of the object instance that is referenced by a variable, rather than the type of the variable.

typedef TMetaClass* TClass;

static ShortString __fastcall ClassName(TClass cls);

ShortString __fastcall ClassName(){ return ClassName(ClassType());}

Description

Use ClassName to find the actual type of an object in the format of a string, such as when passing a string as a parameter to another routine.

Call ClassName with no arguments to determine the name (such as “TButton”) of an object instance.  For example, a variable of an ancestor type can refer to an instance of any descendent type. In this case, ClassName returns a string indicating the actual type of the object, rather than a string containing the type of the declared variable.

Call ClassName passing in a TClass value to obtain the class name from its metaclass information.

ClassName provides information on objects across modules so it is especially useful for exception-handling.


TObject::ClassNameIs

TObject	See also

Determines whether an object is of a specific type.

typedef TMetaClass* TClass;

static bool __fastcall ClassNameIs(TClass cls, const AnsiString string);

bool __fastcall ClassNameIs(const AnsiString string){ return ClassNameIs(ClassType(), stri, ng); }

Description

Use ClassNameIs when writing conditional code based upon an object’s type or to query objects across modules, or DLLs.

Call the static ClassNameIs method to verify that a TClass variable represents a particular class (such as “TButton”). Call ClassNameIs with a single AnsiString parameter to determine whether a particular object instance is of the specified type.

To determine whether an object is of a specified type or one of its descendants, use the InheritsFrom method instead.

ClassNameIs returns true if the string passed in the string parameter matches the name of the class. Otherwise, it returns false.


TObject::ClassParent

TObject	See also 	Example

Returns the type of the immediate ancestor of a class.

typedef TMetaClass* TClass;

static TClass __fastcall ClassParent(TClass cls)

TClass __fastcall ClassParent() { return ClassParent(ClassType());}

Description

Use the ClassParent method to trace the derivation of an object or TClass variable. ClassParent returns NULL for type TObject because TObject has no ancestor class.

ClassParent is used internally in C++Builder to implement the InheritsFrom method. The static version can be used to determine the type of any class reference. ClassParent can also be used to determine the ancestry of a particular object instance.

Note:	Applications should rarely, if ever, call ClassParent directly.  Instead, use the InheritsFrom method or a dynamic cast.


TObject::ClassType

TObject	See also 	Example

Returns a pointer to the run-time type information of an object instance.

typedef TMetaClass* TClass;

TClass  __fastcall ClassType();

Description

ClassType dynamically determines the actual type of an object. Use ClassType to obtain the metaclass information for an object instance. To obtain the metaclass information for a class name, use the __classid routine.


TObject::CleanupInstance

TObject	See also

Performs finalization on long strings, Variants, and interface variables within a class.

void __fastcall CleanupInstance();

Description

Do not call CleanupInstance directly. CleanupInstance is called automatically when the object is destroyed using the delete keyword.

CleanupInstance releases all long strings and Variants. It set long strings to empty and Variants to Unassigned.


TObject::TObject

TObject	See also

Constructs an object and initializes its data before the object is first used.

__fastcall  TObject(){}

Description

Most applications do not need to create instances of TObject. Instead, construct descendants of TObject using the new keyword and passing the arguments for the constructor of a TObject descendant.

The purpose, size and behavior of objects can differ greatly. Descendent objects usually define a constructor that is customized to create that particular kind of object initializing its data as needed.

Note:	If an exception escapes from a constructor, the object’s destructor is called to clean up the failed instance.


TObject::DefaultHandler

TObject	See also

Provides the interface for a method that processes message records.

virtual void __fastcall DefaultHandler(void* Message);

Description

DefaultHandler is called by Dispatch when it cannot find a method for a particular message. DefaultHandler provides message handling for all messages for which an object does not have specific handlers. Descendent classes of TObject that process messages usually define DefaultHandler methods according to the type of messages they handle. For example, TWinControl overrides DefaultHandler to call DefWindowProc.


TObject::~TObject

TObject	See also

Disposes of an object instance.

virtual __fastcall ~TObject(){}

Description

Do not call ~TObject directly. Instead, use the delete keyword when destroying VCL objects.

~TObject does nothing special. Descendent objects usually define a destructor that is customized to destroy that particular kind of object.

Note:	If an exception escapes from the constructor, the destructor will be called to destroy the partially constructed object instance that failed to initialize completely.


TObject::Dispatch

TObject	See also

Calls message-handling methods for the object, based on the contents of the Message parameter.

virtual void __fastcall Dispatch(void *Message);

Description

Call Dispatch to automatically pass messages to the current event handler for an object.

Dispatch determines whether a message is in the list of message handlers declared for the object. If the object does not handle the message, Dispatch then examines the message-handler list of the ancestor class, and continues checking ancestors until it either finds a specific handler or runs out of ancestors, in which case it calls DefaultHandler.

The Message parameter is void * for Dispatches. Although any kind of data can be passed to Dispatch, use a message record such as TMessage or a specific message-record type. TMessage is defined as follows:

struct TMessage

{

  Cardinal Msg;

  union

  {

    struct

    {

      Word WParamLo;

      Word WParamHi;

      Word LParamLo;

      Word LParamHi;

      Word ResultLo;

      Word ResultHi;

    };

    struct

    {

      int WParam;

      int LParam;

      int Result;

    };

  };

};

The only assumption Dispatch makes about the data in Message is that the first two bytes contain a message ID, that is an integer-that determines which message handler Dispatch calls to handle the message.


TObject::FieldAddress

TObject

Returns the address of a published object field.

void *  __fastcall FieldAddress(const ShortString &Name);

Description

FieldAddress is used internally by the C++Builder streaming system to access a specified published field of an object. FieldAddress returns a pointer to the field if it exists. If the object has no published field by that name, FieldAddress returns NULL.

Programs should access and manipulate fields by using properties instead of FieldAddress.


TObject::Free

TObject	See also

Destroys an object and frees its associated memory, if necessary.

__fastcall Free();

Description

Do not call the Free method of an object. Instead, use the delete keyword, which calls Free to destroy an object.

Free automatically calls the destructor if the object instance is not NULL. Any object instantiated at runtime that does not have an Owner should be destroyed by using delete to call Free. Otherwise the object won’t be properly destroyed and the memory released.

Free is successful even if the object is NULL, so if the object was never initialized, for example, Free won’t result in an error.


TObject::FreeInstance

TObject	See also

Deallocates memory allocated by a previous call to the NewInstance method.

virtual void __fastcall FreeInstance();

Description

All destructors call FreeInstance automatically to deallocate memory that was allocated by overriding NewInstance.

Do not call FreeInstance directly. FreeInstance should be overriden if NewInstance was overriden to change the way the object’s instance data was allocated.

Like NewInstance, FreeInstance uses the value returned from InstanceSize to deallocate the object's memory.


TObject::GetInterface

TObject

Retrieves the interface identified by a given identifier.

bool __fastcall GetInterface(const TGUID &IID, void *Obj);

Description

GetInterface is used internally to retrieve any interface implemented by an object. GetInterface is used by the TInterfacedObject to implement the QueryInterface method. An interface type name, such as IUnknown, can be supplied as the IID parameter since the compiler will replace the interface with the associated GUID.

Some VCL objects that are not descended from TInterfacedObject still implement interfaces. Use GetInterface to obtain the interface from these objects.

GetInterface returns, as the parameter Obj, a pointer to the interface identified by the IID parameter. If the interface is supported by the object, GetInterface returns true. If the interface is not supported by the object, GetInterface returns false, and the Obj parameter is NULL.


TObject::GetInterfaceEntry

TObject

Returns the entry for a specific interface implemented in a class.

struct PACKAGE TInterfaceEntry

{

  TGUID IID;

  void* VTable;

  int IOffset;

};

typedef TInterfaceEntry *PInterfaceEntry;

static PInterfaceEntry __fastcall GetInterfaceEntry(const TGUID IID);

Description

GetInterfaceEntry returns the entry for the interface, specified by the IID parameter, in the class. GetInterfaceEntry is used internally. It is rarely called directly.

Note:	One use for this method is to describe to OLE how to automatically dispatch calls to a dual-IDispatch interface. An interface type name, such as IUnknown, can be supplied as the IID parameter since the compiler will replace the interface with the associated GUID.


TObject::GetInterfaceTable

TObject	See also

Returns pointer the a structure containing all of the interfaces implemented by a given class.

struct PACKAGE TInterfaceEntry

{

  TGUID IID;

  void* VTable;

  int IOffset;

};

struct PACKAGE TInterfaceTable

{

  int EntryCount;

  TInterfaceEntry Entries[];

};

typedef TInterfaceTable *PInterfaceTable;

static PInterfaceTable * __fastcall GetInterfaceTable(void);

Description

GetInterfaceTable returns the TInterfaceEntry’s for the class. This list only contains interfaces implemented by this class, not its ancestor. To find the ancestor list, call GetParentClass and then call its GetInterfaceTable method. To find the entry for a specific interface, use the GetInterfaceEntry method instead.


TObject::InheritsFrom

TObject	See also

Determines the relationship of two object types.

typedef TMetaClass* TClass;

static bool __fastcall InheritsFrom(TClass cls, TClass aClass);

bool __fastcall InheritsFrom(TClass aClass) { return InheritsFrom(ClassType(), aClass);}

Description

Use InheritsFrom to determine if a particular class type or object is an instance of a class or one of its descendants. InheritsFrom returns true if the object type specified in the aClass parameter is an ancestor of the object type or the type of the object itself. Otherwise, it returns false.

InheritsFrom is useful in determining whether a descendant class method or property can be used, given a variable of a base class. For example, use Inherits from to determine whether the Sender parameter in an event handler is of a particular class type or one of its descendants.

Use the ClassNameIs method when the class type must match exactly, without returning true if the class is an ancestor class.


TObject::InitInstance

TObject	See also

Initializes a newly allocated object instance to all zeros and initializes the instance’s virtual method table pointer.

typedef TMetaClass* TClass;

static TObject * __fastcall InitInstance(TClass cls, void *instance);

TObject * __fastcall InitInstance(void *instance) { TObject::InitInstance(this, instance); }

Description

There should be no reason to call InitInstance directly. InitInstance is called automatically by NewInstance when an object is created. When overriding NewInstance be sure to call InitInstance as the last statement.

InitInstance is not virtual, so you cannot override it. Initialize any data for an object in the constructor. Override NewInstance only for special memory allocation requirements, such as allocating all instances of a class type from a common memory pool.


TObject::InstanceSize

TObject	See also

Returns the size in bytes of each instance of the object type.

typedef TMetaClass* TClass;

static long __fastcall InstanceSize(TClass cls);

long __fastcall InstanceSize(){ return InstanceSize(ClassType()); }

Description

Use InstanceSize to determine how many bytes of memory are required for a class’s instance data. C++Builder uses InstanceSize internally for methods that allocate and deallocate memory. InstanceSize is not a virtual method, so it cannot be overridden. InitInstance should only be called in the context of implementing a custom version of NewInstance.


TObject::MethodAddress

TObject	See also

Returns the address of a published method.

typedef TMetaClass* TClass;

static void * __fastcall MethodAddress(TClass cls, const ShortString &Name);

void * __fastcall MethodAddress(const ShortString &Name) { return MethodAddress(ClassType(), Name); }

Description

MethodAddress is used internally in C++Builder by the streaming system. MethodAddress is used to convert a method name, specified by Name, to a pointer containing the method address when reading in from a stream. There should be no need to call MethodAddress directly.

If Name does not specify a published method for the object, MethodAddress returns NULL.


TObject::MethodName

TObject	See also

Returns a string containing the name of the method located at Address.

typedef TMetaClass* TClass;

static ShortString __fastcall MethodName(TClass cls, void *Address);

ShortString __fastcall MethodName(void *Address) { return MethodName(ClassType(), Address); }

Description

MethodName is used internally in C++Builder by the streaming system. MethodName is used to convert a pointer containing the method address to a string containing the method name when writing event properties to a stream. It is essentially the counterpart to MethodAddress. There should be no need to call MethodName directly.

If Address does not point to a published method of the object, MethodName returns an empty string.


TObject::NewInstance

TObject	See also

Allocates memory for each instance of an object type and returns a pointer to that new instance.

typedef TMetaClass* TClass;

virtual TObject* __fastcall NewInstance(TClass cls);

Description

All constructors call NewInstance automatically. NewInstance calls InstanceSize to determine how much memory to allocate from the heap to contain a particular instance. Do not call NewInstance directly.

A descendent class can override NewInstance to change the way that particular class allocates its memory. Overriding NewInstance to change the memory allocation for an object type, might necessitate overriding FreeInstance to deallocate that same memory. For example, when allocating a large number of identical objects that all need to be in memory at the same time, one could allocate a large block of memory for the entire group, then override NewInstance to use part of that larger block for each instance.

When overriding NewInstance call InitInstance as the last statement.

Note:	By default NewInstance calls InitInstance.


TObject::SafeCallException

TObject

Handles OLE exceptions.

virtual HResult __fastcall SafeCallException(TObject *ExceptObject, void *ExceptAddr);

Description

SafeCallException is used for OLE exception handling support. For TObject SafeCallException returns E_UNEXPECTED. This is a default case that is appropriate for classes that do not support any interfaces. Classes that implement COM and OLE interfaces should override this method to handle other errors that might occur. COM and OLE classes in C++Builder override SafeCallException.


Hierarchy


 TOleContainer

Hierarchy	Properties	Methods	Events	See also

TOleContainer embeds or links OLE objects.

Unit

olectnrs

Description

Use TOleContainer to handle many of the complexities of OLE 2.0. TOleContainer lets the user choose an OLE object to insert by simply calling the InsertObjectDialog method. TOleContainer can create either an embedded OLE object or a linked OLE object.

TOleContainer automatically handles menu merging, the process of combining the container form's menu with that of an in-place activated OLE object's server application. The menu items' GroupIndex property settings control how menus are merged. Those main menu items with GroupIndex values of 0, 2, and 4 remain; TOleContainer merges the server application's menus and replaces the main menu items with GroupIndex values of 1, 3, and 5 (if they exist).

OLE objects that are activated in-place add their servers' toolbars directly into the container application's window. Normally, any panels used for toolbars are replaced by the OLE object's server's toolbars. Prevent this by setting a panel's Locked property to true.

When using TOleContainer in an SDI application (the main form's FormStyle property is fsNormal rather than fsMDIForm), place the TOleContainer component inside a panel whose Align property is set to alClient. TOleContainer replaces an SDI form's toolbars as described above, and using a panel automatically adjusts the amount of space available to the OLE container.


TOleContainer properties

TOleContainer	Alphabetically	Legend

In TOleContainer

AllowActiveDoc

AllowInPlace

AutoActivate

AutoVerbMenu

BorderStyle

CanPaste

CopyOnSave

Iconic

Linked

Modified

NewInserted

ObjectVerbs

OldStreamFormat

OleClassName

OleObject

OleObjectInterface

PrimaryVerb

SizeMode

SourceDoc

State

StorageInterface

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TOleContainer properties

TOleContainer	By object	Legend

Align

AllowActiveDoc

AllowInPlace

AutoActivate

AutoVerbMenu

BorderStyle

BoundsRect

Brush

CanPaste

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

CopyOnSave

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Handle

Height

HelpContext

Hint

Iconic

Left

Linked

Modified

Name

NewInserted

ObjectVerbs

OldStreamFormat

OleClassName

OleObject

OleObjectInterface

Owner

Parent

ParentColor

ParentCtl3D

ParentShowHint

ParentWindow

PopupMenu

PrimaryVerb

ShowHint

Showing

SizeMode

SourceDoc

State

StorageInterface

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TOleContainer::AllowActiveDoc

TOleContainer	See also

Specifies whether the OLE container supports the IOleDocumentSite interface.

__property bool AllowActiveDoc = {read=FAllowActiveDoc, write=FAllowActiveDoc, default=1};

Description

Set AllowActiveDoc to true to specify that the OLE container can house an ActiveDoc (DocObject). Set AllowActiveDoc to false to limit the OLE container to hosting OLE controls that use the more usual interfaces such as IOleClientSite. ActiveDoc-enabled controls have a slightly different border. Set AllowActiveDoc to false to maintain a consistent appearance in forms that do not need to support the IOleDocumentSite interface.


TOleContainer::AllowInPlace

TOleContainer	See also

Determines whether the OLE container allows inplace activation.

__property bool AllowInPlace = {read=FAllowInPlace, write=FAllowInPlace, default=1};

Description

Set AllowInPlace to specify what happens when the user activates the OLE object. If AllowInPlace is true and Iconic is false, the OLE object is activated inplace. If AllowInPlace is false, the OLE object is activated in a separate window. The default value is true.


TOleContainer::AutoActivate

TOleContainer	See also

Determines how the object in an OLE container is activated.

__property TAutoActivate AutoActivate = {read=FAutoActivate, write=FAutoActivate, default=2};

Description

Set AutoActivate to specify what actions activate the OLE object. AutoActivate takes one of the values in the following table:

Values	Meaning

aaManual	The OLE object must be activated programatically by calling DoVerb(ovShow).

aaGetFocus	The OLE object is activated when the OLE container gets focus (by clicking on it with the mouse or pressing Tab to move the focus to it).

aaDoubleClick	(Default) The OLE object is activated by doubleclicking it or pressing Enter while the container has the focus.


TOleContainer::AutoVerbMenu

TOleContainer	See also

Determines whether the OLE container automatically creates a pop-up menu containing the OLE object's verbs.

__property bool AutoVerbMenu = {read=FAutoVerbMenu, write=FAutoVerbMenu, default=1};

Description

Use AutoVerbMenu to specify whether the OLE object can replace the OLE container’s popup menu. If AutoVerbMenu is true (the default), the OLE object replaces any existing PopupMenu property. If AutoVerbMenu is false, no popup menu is automatically created.


TOleContainer::BorderStyle

TOleContainer	See also

Determines whether a single line is drawn around the OLE container.

__property Forms::TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Set BorderStyle to specify whether a the OLE container should be framed by a single line. These are the possible values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border


TOleContainer::CanPaste

TOleContainer	See also

Indicates whether the Windows clipboard contains an OLE object that can be pasted into the OLE container.

__property bool CanPaste = {read=GetCanPaste, nodefault};

Description

Read CanPaste before trying to paste or paste link an OLE object from the clipboard.


TOleContainer::CopyOnSave

TOleContainer	See also

Determines whether the SaveToFile and SaveToStream methods first create a copy of the OLE object.

__property bool CopyOnSave = {read=FCopyOnSave, write=FCopyOnSave, default=1};

Description

When CopyOnSave is true, the SaveToFile and SaveToStream methods create a temporary OLE object, compressing redundant data to save space. This compressed copy is then saved to the file or stream. When CopyOnSave is false, the OLE object is saved directly to the file or stream without using a temporary copy to compress redundant information.

Set CopyOnSave to false when the container holds very large embedded objects and there might not be enough memory to make the temporary copy. The default value is true.


TOleContainer::Iconic

TOleContainer	See also

Determines whether the OLE object is displayed as an icon.

__property bool Iconic = {read=GetIconic, write=SetIconic, stored=false, nodefault};

Description

Set Iconic to specify whether the OLE container displays the icon for the server application instead of the image of the object. If Iconic is true, the OLE object is displayed as an icon; if false, it's displayed as it would be in the server application.


TOleContainer::Linked

TOleContainer	See also

Indicates whether the OLE object is linked or embedded.

__property bool Linked = {read=GetLinked, nodefault};

Description

Read Linked to determine whether the OLE object is linked to the OLE server. If Linked is true, the OLE object is linked; if false, it's embedded. An OLE object must already be loaded in the container before accessing the Linked property.


TOleContainer::Modified

TOleContainer	See also

Indicates whether the OLE object has been modified.

__property bool Modified = {read=FModified, write=FModified, nodefault};

Description

Use Modified to determine when the OLE object has been modified (including being deleted or replaced by another OLE object). To keep track of incremental changes, set Modified to false and later check it to see if the OLE object has been modified after since Modified was set to false. If there is no OLE object loaded into the container, Modified returns false.


TOleContainer::NewInserted

TOleContainer	See also

Indicates whether the OLE object was created rather than pasted in or created as a link to a file.

__property bool NewInserted = {read=FNewInserted, nodefault};

Description

Read NewInserted to determine whether the OLE object was newly created via a call to InsertObjectDialog. If there is no OLE object loaded into the container, NewInserted returns false. If NewInserted is true after a call to InsertObjectDialog, call DoVerb(ovShow) to let the user edit the object.


TOleContainer::ObjectVerbs

TOleContainer	See also

Lists the verbs that the OLE object supports.

__property Classes::TStrings* ObjectVerbs = {read=GetObjectVerbs};

Description

Read ObjectVerbs to determine the verbs that can be used with the OLE object. The verb names can have embedded ampersand (&) characters to indicate shortcut keys. An OLE object must already be loaded in the container before accessing the ObjectVerbs property.


TOleContainer::OldStreamFormat

TOleContainer	See also

Indicates whether the OLE object is loaded and saved using the C++Builder 1.0 format.

__property bool OldStreamFormat = {read=FOldStreamFormat, write=FOldStreamFormat, default=0};

Description

Set OldStreamFormat to true to read OLE objects that were saved to file using C++Builder 1.0 or to save OLE objects that will be used by C++Builder 1.0. If OldStreamFormat is false (the default), the LoadFromFile, LoadFromStream, SaveToFile, and SaveToStream methods use the newer format that contains extra header information. The extra header information is used to validate a file or stream. This property is provided for backward compatibility only.


TOleContainer::OleClassName

TOleContainer	See also

Specifies the class name of the OLE object.

__property System::AnsiString OleClassName = {read=GetOleClassName};

Description

Read OleClassName to obtain the class name (programmatic identifier) for the OLE object. The class name is a string describing the class of OLE object that is registered in the Windows registry. An OLE object must already be loaded in the container before accessing the OleClassName property.


TOleContainer::OleObject

TOleContainer	See also

Represents the OLE object hosted by the OLE container.

__property System::Variant OleObject = {read=GetOleObject};

Description

Read OleObject to access the OLE object hosted by the OLE container as a variant. To interact with the OLE object using the IOleObject interface, use the OleObjectInterface property instead. If the OLE object is not loaded in the container before reading OleObject, an EOleError exception is raised.


TOleContainer::OleObjectInterface

TOleContainer	See also

Provides access to the IOleObject interface for the OLE object.

__property _di_IOleObject OleObjectInterface = {read=FOleObject};

Description

Use OleObjectInterface for low-level access to the OLE API. If there is no OLE object loaded into the container, OleObjectInterface returns NULL.


TOleContainer::PrimaryVerb

TOleContainer	See also

Specifies the index of the primary (default) verb for the OLE object.

__property int PrimaryVerb = {read=GetPrimaryVerb, nodefault};

Description

Use PrimaryVerb to determine which verb in the ObjectVerbs list specifies the default action for the OLE object. In a call to the DoVerb method, DoVerb(ovPrimary) is the same as DoVerb(PrimaryVerb). An OLE object must already be loaded in the container before accessing the PrimaryVerb property.


TOleContainer::SizeMode

TOleContainer	See also

Determines how the OLE object is sized in the OLE container.

__property TSizeMode SizeMode = {read=FSizeMode, write=SetSizeMode, default=0};

Description

Set SizeMode to specify how the OLE object is fit into the client area of the OLE container. The following table gives the possible values :

Value	Meaning

smClip	(Default)- Displays the OLE object at its normal size, clipping any parts that don't fit within the container.

smCenter	Displays the OLE object at its normal size, centering it within the container.

smScale	Scales or shrinks the view of the OLE object to fit within the container, by scaling width and height proportionally.

smStretch	Scales or shrinks the view of the OLE object to fill the OLE container, without regard to preserving the proportions of the OLE object.

smAutoSize	Displays the OLE object at its normal size and automatically resizes the container to fit the size of the OLE object.


TOleContainer::SourceDoc

TOleContainer	See also

Specifies the name of the source document for a linked OLE object.

__property System::AnsiString SourceDoc = {read=GetSourceDoc};

Description

Read SourceDoc to obtain the name of the OLE object when it is linked. An OLE object must already be loaded in the container before accessing the SourceDoc property. If the OLE object isn't linked, SourceDoc returns an empty string.


TOleContainer::State

TOleContainer	See also

Describes the state of the OLE object.

__property TObjectState State = {read=GetState, nodefault};

Description

Read State to determine the state of the OLE object and its server application. State has one of the following values:

Values	Meaning

osEmpty	There is no OLE object in the container.

osLoaded	There is an OLE object in the container, but its server application isn't currently running.

osRunning	The OLE object's server is running.

osOpen	The OLE object is open in a separate window.

osInPlaceActive	The OLE object is activated inplace, but  hasn't yet merged its menus or toolbars. This is an intermediate state; the State property will shift to osUIActive as soon as the menus and toolbars have been merged.

osUIActive	The OLE object is activated inplace and menus and toolbars have been merged


TOleContainer::StorageInterface

TOleContainer	See also

Provides access to the IStorage interface for the OLE object.

__property _di_IStorage StorageInterface = {read=FStorage};

Description

Use StorageInterface for low-level access to the OLE API. If there is no OLE object loaded into the container, StorageInterface returns NULL.


TOleContainer events

TOleContainer	Alphabetically	Legend

In TOleContainer

OnActivate

OnDeactivate

OnObjectMove

OnResize

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TOleContainer events

TOleContainer	By object	Legend

OnActivate

OnDeactivate

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnObjectMove

OnResize

OnStartDrag


TOleContainer::OnActivate

TOleContainer	See also

Occurs immediately after the OLE object is activated.

__property Classes::TNotifyEvent OnActivate = {read=FOnActivate, write=FOnActivate};

Description

Write an OnActivate event handler to take specific action when the OLE object becomes active.


TOleContainer::OnDeactivate

TOleContainer	See also

Occurs immediately after the OLE object is deactivated.

__property Classes::TNotifyEvent OnDeactivate = {read=FOnDeactivate, write=FOnDeactivate};

Description

Write an OnDeactivate event handler to respond when the OLE object is deactivated.


TOleContainer::OnObjectMove

TOleContainer	See also

Occurs when the OLE container is notified that the OLE object has moved or resized.

__property TObjectMoveEvent OnObjectMove = {read=FOnObjectMove, write=FOnObjectMove};

Description

Write an OnObjectMove event handler to respond when the OLE object changes size or position. The Bounds parameter specifies the boundaries of the in-place object in the client coordinates of OLE container. OnObjectMove occurs before the OLE object’s image is updated to reflect the change.


TOleContainer::OnResize

TOleContainer	See also

Occurs immediately after the OLE container window is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

Write an OnResize event handler to respond to changes in the size of the OLE container window. If SizeMode is smAutoSize, the container window changes size whenever the OLE object resizes.


TOleContainer methods

TOleContainer	Alphabetically

In TOleContainer

~TOleContainer

ChangeIconDialog

Close

Copy

CreateLinkToFile

CreateObject

CreateObjectFromFile

CreateObjectFromInfo

DestroyObject

DoVerb

GetIconMetaPict

InsertObjectDialog

LoadFromFile

LoadFromStream

ObjectPropertiesDialog

Paste

PasteSpecialDialog

Run

SaveAsDocument

SaveToFile

SaveToStream

TOleContainer

UpdateObject

UpdateVerbs

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TOleContainer methods

TOleContainer	By object

~TOleContainer

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ChangeIconDialog

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

ContainsControl

ControlAtPos

Copy

CreateLinkToFile

CreateObject

CreateObjectFromFile

CreateObjectFromInfo

DefaultHandler

DestroyComponents

Destroying

DestroyObject

DisableAlign

Dispatch

DoVerb

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetIconMetaPict

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InsertObjectDialog

InstanceSize

Invalidate

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

ObjectPropertiesDialog

PaintTo

Paste

PasteSpecialDialog

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

Run

SafeCallException

SaveAsDocument

SaveToFile

SaveToStream

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TOleContainer

Update

UpdateControlState

UpdateObject

UpdateVerbs


TOleContainer::ChangeIconDialog

TOleContainer	See also

Displays the Change Icon OLE dialog box.

bool __fastcall ChangeIconDialog(void);

Description

Call ChangeIconDialog to let the user choose a different icon (from .ICO, .DLL, and .EXE files) to use when displaying the OLE object as an icon. An OLE object must already be loaded before calling ChangeIconDialog. ChangeIconDialog returns true if the dialog box was successfully displayed and the user chose the OK button. ChangeIconDialog returns false otherwise.


TOleContainer::Close

TOleContainer	See also

Deactivates the OLE object.

void __fastcall Close(void);

Description

Call Close to deactivate the OLE object and terminate its server application, without removing it from the container. Any changes the user made to the OLE object are automatically saved. After calling Close, the container's State property is osLoaded.

Note:	If Close is called when no OLE object is loaded, TOleContainer raises an exception.


TOleContainer::Copy

TOleContainer	See also

Copies the OLE object to the Windows clipboard.

void __fastcall Copy(void);

Description

Call Copy to write the OLE object to the clipboard. If there is no OLE object in the container, Copy raises an exception.


TOleContainer::TOleContainer

TOleContainer	See also

Creates and initializes an instance of TOleContainer.

__fastcall virtual TOleContainer(Classes::TComponent* AOwner);

Description

Call TOleContainer to instantiate a TOleContainer object at runtime. OLE containers placed on forms at design time are created automatically. After calling the parent object’s constructor, TOleContainer

•	Sets ControlStyle to [csClickEvents, csSetCaption, csOpaque, csDoubleClicks].

•	Sets TabStop to true.

•	Sets ParentColor to false and BorderStyle to bsSingle.

•	Sets AllowActiveDoc and AllowInPlace to true.

•	Sets AutoActivate to aaDoubleClick and AutoVerbMenu to true.

•	Sets CopyOnSave to true.


TOleContainer::TOleContainer
TOleContainer::CreateLinkToFile

TOleContainer	See also

Creates a linked OLE object from the contents of a file.

void __fastcall CreateLinkToFile(const System::AnsiString FileName, bool Iconic);

Description

Call CreateLinkToFile to create a linked OLE object from the file specified by the FileName parameter. Iconic specifies whether the object is shown as an icon (true) or displayed as it would be in the server application (false). If there is already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::TOleContainer
TOleContainer::CreateObject

TOleContainer	See also

Creates an embedded OLE object given its class name (also known as programmatic identifier).

void __fastcall CreateObject(const System::AnsiString OleClassName, bool Iconic);

Description

Call CreateObject to create an OLE object using the class name (also known as programmatic identifier) specified by the OleClassName parameter. The Iconic parameter indicates whether the object is shown as an icon (true) or displayed as it would be in the server application (false). If there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::TOleContainer
TOleContainer::CreateObjectFromFile

TOleContainer	See also

Creates an embedded OLE object from the contents of a file.

void __fastcall CreateObjectFromFile(const System::AnsiString FileName, bool Iconic);

Description

Call CreateObjectFromFile to create an OLE object from the file specified by the FileName parameter. The Iconic parameter indicates whether the object is shown as an icon (true) or displayed as it would be in the server application (false). If there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::TOleContainer
TOleContainer::CreateObjectFromInfo

TOleContainer	See also

Creates an OLE object matching the specified TCreateInfo record.

void __fastcall CreateObjectFromInfo(const TCreateInfo &CreateInfo);

Description

Call CreateObjectFromInfo to create a linked or embedded OLE object object based on the specifications in the CreateInfo parameter. CreateInfo specifies whether the object should be created from a file, from a data transfer object, or from a class identifier, and provides the necessary supporting information. CreateInfo also indicates whether the OLE object should be displayed as an Icon, and allows the icon to be specified. If there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.

Note:	The CreateLinkToFile, CreateObject, and CreateObjectFromFile methods are oneline calls for the most common types of OLE objects. They can be used instead of filling out the TCreateInfo record.


TOleContainer::~TOleContainer

TOleContainer	See also

Destroys an instance of TOleContainer.

__fastcall virtual ~TOleContainer(void);

Description

Do not call ~TOleContainer directly in an application. Instead, call Free. Free verifies that the OLE container is not already freed, and only then calls ~TOleContainer. ~TOleContainer frees the OLE object before calling the parent object’s destructor.


TOleContainer::~TOleContainer
TOleContainer::DestroyObject

TOleContainer	See also

Destroys the container’s OLE object.

void __fastcall DestroyObject(void);

Description

Call DestroyObject to destroy the OLE object, discarding any unsaved changes the user made to it.


TOleContainer::DoVerb

TOleContainer	See also

Requests that the OLE object perform some action.

void __fastcall DoVerb(int Verb);

Description

Call DoVerb to request that the OLE object perfom one of the actions listed by the ObjectVerbs property. OLE defines several verbs, such as ovShow (to display the OLE object) and ovPrimary (the default action, usually to activate the OLE object). OLE objects can also define their own custom verbs. Use the ObjectVerbs property to get a list of those custom verbs.


TOleContainer::GetIconMetaPict

TOleContainer	See also

Returns the global memory handle of a metafile containing the OLE object's icon.

int __fastcall GetIconMetaPict(void);

Description

Call GetIconMetaPict to obtain a metafile handle for drawing the OLE object’s icon on another canvas. Use the global DestroyMetaPict procedure to destroy the handle. If the OLE container is empty, GetIconMetaPict raises an exception.


TOleContainer::InsertObjectDialog

TOleContainer	See also

Displays the Insert Object OLE dialog box.

bool __fastcall InsertObjectDialog(void);

Description

Call InsertObjectDialog to let the user create an OLE object. The OLE object can be embedded or linked. InsertObjectDialog returns true if the dialog box was successfully displayed and the user chose the OK button. InsertObjectDialog returns false otherwise. If the user chose OK and there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::LoadFromFile

TOleContainer	See also

Loads an OLE object from the specified file.

void __fastcall LoadFromFile(const System::AnsiString FileName);

Description

Call LoadFromFile to load an OLE object that was saved using the SaveToFile method. If OldStreamFormat is true, LoadFromFile loads files saved by C++Builder 1.0's TOleContainer object as well as files saved using the current format; if OldStreamFormat is false, LoadFromFile will not load files saved by C++Builder 1.0. If there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::LoadFromStream

TOleContainer	See also

Loads an OLE object from the specified stream.

void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

Call LoadFromStream to load an OLE object from a stream. If OldStreamFormat is true, LoadFromStream loads OLE objects saved by C++Builder 1.0's TOleContainer object as well as OLE objects saved using the current format; if OldStreamFormat is false, LoadFromStream will not load OLE objects saved by C++Builder 1.0. If there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::ObjectPropertiesDialog

TOleContainer	See also

Displays the OLE Object Properties property sheet.

bool __fastcall ObjectPropertiesDialog(void);

Description

Call ObjectPropertiesDialog to let the user see and edit the properties of the OLE object. Any changes the user makes in the property sheet are automatically made to the OLE object. ObjectPropertiesDialog returns true if the property sheet was successfully displayed and the user chose the OK button. It returns false otherwise.

If the OLE container is empty, ObjectPropertiesDialog raises an exception.


TOleContainer::Paste

TOleContainer	See also

Pastes the contents of the Windows clipboard as an embedded object.

void __fastcall Paste(void);

Description

Call Paste to embed the object on the clipboard in the OLE container. If there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer::PasteSpecialDialog

TOleContainer	See also

Displays the Paste Special OLE dialog box.

bool __fastcall PasteSpecialDialog(void);

Description

Call PasteSpecialDialog to let the user control how the contents of the Windows clipboard are pasted into the container. The Paste Special dialog box lets the user select the format of the data, whether it should be embedded or linked, and whether the OLE object should be displayed as an icon (and if so, to choose a different icon). PasteSpecialDialog returns true if the dialog box was successfully displayed and the user chose the OK button. It returns false otherwise. If the user chose the OK button when there's already an OLE object in the container, it is destroyed and any changes the user made to it are discarded.


TOleContainer.Run

TOleContainer	See also

Runs the OLE object's server application, but doesn't open or active the OLE object iself.

void __fastcall Run(void);

Description

Call Run to ensure that the server application is running. Once the server application is running, opening and activating the OLE object happens much more quickly. An OLE object must already be loaded in the container before calling Run, Otherwise, Run raises an exception.


TOleContainer::SaveAsDocument

TOleContainer	See also

Saves the OLE object to the specified file in native OLE Document format.

void __fastcall SaveAsDocument(const System::AnsiString FileName);

Description

Call SaveAsDocument to save the OLE object in its native OLE Document format. An OLE object must already be loaded in the container before calling SaveAsDocument. Otherwise, SaveAsDocument raises an exception.

Note:	Saving an OLE object to a file or a stream limits the ability of another application, such as Word, to open the file, even if it is saved with the correct extension. Saving to a file or a stream loses information necessary to open such a file. Use SaveAsDocument when needing to save files in a native OLE Document format.


TOleContainer::SaveToFile

TOleContainer	See also

Saves the OLE object to the specified file.

void __fastcall SaveToFile(const System::AnsiString FileName);

Description

Call SaveToFile to save the OLE object. If CopyOnSave is true, SaveToFile first creates a temporary OLE object that compresses redundant data, saving space in the file that is saved. If OldStreamFormat is true, SaveToFile writes a file that can be read by C++Builder 1.0's TOLEContainer component.

An OLE object must already be loaded in the container before calling SaveToFile. Otherwise, SaveToFile raises an exception.


TOleContainer::SaveToStream

TOleContainer	See also

Saves the OLE object to the specified stream.

void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Call SaveToStream to save the OLE object. If CopyOnSave is true, SaveToStream first creates a temporary OLE object that compresses redundant data, reducing the information that must be saved. If OldStreamFormat is true, SaveToStream writes the object in a format that can be read by C++Builder 1.0's TOLEContainer component.

An OLE object must already be loaded in the container before calling SaveToStream. Otherwise, SaveToStream raises an exception.


TOleContainer::UpdateObject

TOleContainer	See also

Refreshes the OLE object.

void __fastcall UpdateObject(void);

Description

Linked OLE objects and embedded objects that contain linked OLE objects get out of date when the source of the link is updated. UpdateObject rereads the source to ensure that the OLE object has current data. If there is no OLE object loaded in the container, UpdateObject has no effect.


TOleContainer::UpdateVerbs

TOleContainer	See also

Refreshes the list of verbs the OLE object can respond to.

void __fastcall UpdateVerbs(void);

Description

TOleContainer automatically calls UpdateVerbs when the ObjectVerbs property is first read, but some OLE objects change their verbs when they perform some actions. The Media Clip OLE object, for example, changes its Play verb to Stop while running. Call UpdateVerbs to ensure that the list of verbs is appropriate to the state of the OLE object.

An OLE object must already be loaded in the container before calling UpdateVerbs. Otherwise, UpdateVerbs raises an exception.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl


TOleControl

Hierarchy	Properties	Methods	See also

TOleControl is the base class from which ActiveX controls are derived.

Unit

olectrls

Description

TOleControl is derived from TWinControl and handles the interactions with OLE necessary for using ActiveX controls in the C++Builder environment. It is unlikely that you will ever need to derive a component from this class.


TOleControl properties

TOleControl	Alphabetically	Legend

In TOleControl

Name

OleObject

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TOleControl properties

TOleControl	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Left

Name

OleObject

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TOleControl::Name

TOleControl

Name is the name of the associated ActiveX control.

__property System::AnsiString Name = {read=FName, write=SetName, stored=false};

Description

Name is used to get the name of the ActiveX control associated with the OLE control object.


TOleControl::OleObject

TOleControl

OleObject is the ActiveX control associated with the TOleControl object.

__property System::Variant OleObject = {read=GetOleObject};

Description

OleObject is used to get the ActiveX control that is associated with the TOleControl.


TOleControl methods

TOleControl	Alphabetically

In TOleControl

~TOleControl

BrowseProperties

DoObjectVerb

GetEnumPropDesc

GetHelpContext

GetObjectVerbs

GetPropDisplayString

GetPropDisplayStrings

IsCustomProperty

SetBounds

SetPropDisplayString

ShowAboutBox

TOleControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TOleControl methods

TOleControl	By object

~TOleControl

Assign

BeginDrag

BringToFront

Broadcast

BrowseProperties

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DoObjectVerb

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetEnumPropDesc

GetHelpContext

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetObjectVerbs

GetParentComponent

GetPropDisplayString

GetPropDisplayStrings

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

IsCustomProperty

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetPropDisplayString

SetTextBuf

Show

ShowAboutBox

TOleControl

Update

UpdateControlState


TOleControl::BrowseProperties

TOleControl

BrowseProperties notifies the ActiveX control to display its Properties dialog box.

void __fastcall BrowseProperties(void);

Description

Use BrowseProperties to notify the ActiveX control to display its Properties dialog box. The Properties dialog box contains property pages for the ActiveX control.


TOleControl::TOleControl

TOleControl	See also

TOleControl creates a new instance of the TOleControl object.

__fastcall virtual TOleControl(Classes::TComponent* AOwner);

Description

Use TOleControl to create a new instance of the TOleControl object. TOleControl calls the parent object’s constructor method and creates and initializes internal objects.


TOleControl::~TOleControl

TOleControl	See also

~TOleControl frees the memory associated with this instance of the TOleControl object.

__fastcall virtual ~TOleControl(void);

Description

Do not call ~TOleControl. Instead, call Free, which calls ~TOleControl if this instance of the TOleControl object is not NULL.


TOleControl::DoObjectVerb

TOleControl

DoObjectVerb notifies the ActiveX control to perform one of its actions.

void __fastcall DoObjectVerb(int Verb);

Description

Use DoObjectVerb to notify the ActiveX control to perform one of its actions. Verb is an integer that corresponds to the action.  Most application-defined verbs are small positive integers.  In addition,

VerbName	Verb
OLEIVERB_PRIMARY	0
OLEIVERB_SHOW	–1
OLEIVERB_OPEN	–2
OLEIVERB_HIDE	–3
OLEIVERB_UIACTIVATE	–4
OLEIVERB_INPLACEACTIVATE	–5
OLEIVERB_DISCARDUNDOSTATE	–6
OLEIVERB_PROPERTIES	–7
For more information about verbs, search the OLE.HLP file or the latest Microsoft Developer Network CD.


TOleControl::GetEnumPropDesc

TOleControl

GetEnumPropDesc returns descriptions of the ActiveX control’s properties.

TEnumPropDesc* __fastcall GetEnumPropDesc(int DispID);

Description

Use GetEnumPropDesc to return descriptions of the ActiveX control’s properties. GetEnumPropDesc returns the descriptions in a TEnumPropDesc object.


TOleControl::GetHelpContext

TOleControl

GetHelpContext retrieves the Help context of a member of the ActiveX control.

bool __fastcall GetHelpContext(System::AnsiString Member, int &HelpCtx, System::AnsiString &HelpFile);

Description

Use GetHelpContext to retrieve the Help context of a member of the ActiveX control.

Member is the name of a property, method, or event of the ActiveX control. To retrieve the help context of the ActiveX control itself, set Member to NULL.

HelpCtx is a variable in which the Help context identifier of Member is to be stored.

HelpFile is a variable in which the name of the Help file containing HelpCtx is to be stored.

The information about the ActiveX control is retrieved from its ITypeInfo interfaces. For more information, search the OLE.HLP file for ITypeInfo.

GetHelpContext returns false if Member is not found; otherwise, GetHelpContext returns true.


TOleControl::GetObjectVerbs

TOleControl

GetObjectVerbs retrieves the names of the verbs implemented by the ActiveX control.

void __fastcall GetObjectVerbs(Classes::TStrings* List);

Description

Use GetObjectVerbs to retrieve the names of the verbs implemented by the ActiveX control.

List is where the names of the verbs are to be stored.


TOleControl::GetPropDisplayString

TOleControl	See also

GetPropDisplayString returns the display string for an interface for the ActiveX control.

System::AnsiString __fastcall GetPropDisplayString(int DispID);

Description

GetPropDisplayString returns the display string for an interface for the ActiveX control.

DispID is the identifier for the interface. For more information, search the OLE.HLP file for DISPID.

For more information about GetPropDisplayString, search the latest Microsoft Developer Network CD for GetDisplayStrings.


TOleControl::GetPropDisplayStrings

TOleControl	See also

GetPropDisplayStrings returns the display strings for an interface for the ActiveX control.

void __fastcall GetPropDisplayStrings(int DispID, Classes::TStrings* List);

Description

GetPropDisplayString returns the display strings for an interface for the ActiveX control.

DispID is the identifier for the interface. For more information, search the OLE.HLP file for DISPID.

List is where the strings are to be stored.

For more information about GetPropDisplayStrings, search the latest Microsoft Developer Network CD for GetDisplayStrings.


TOleControl::IsCustomProperty

TOleControl

IsCustomProperty indicates whether an interface for the ActiveX control is a custom property.

bool __fastcall IsCustomProperty(int DispID);

Description

Use IsCustomProperty to determine whether an interface for the ActiveX control is a custom property.

DispID is the identifier for the interface. For more information, search the OLE.HLP file for DISPID.

IsCustomProperty returns true if an interface is a custom property; otherwise, IsCustomProperty returns false.


TOleControl::SetBounds

TOleControl

SetBounds sets the boundaries of the ActiveX control.

virtual void __fastcall SetBounds(int ALeft, int ATop, int AWidth, int AHeight);

Description

Use SetBounds to set the boundaries of the ActiveX control.

ALeft, ATop, AWidth, and AHeight are the x-coordinate of the upper-left corner, the y-coordinate of the upper-left corner, the width and the height of the ActiveX control.


TOleControl::SetPropDisplayString

TOleControl	See also

SetPropDisplayString sets the display string for an interface for the ActiveX control.

void __fastcall SetPropDisplayString(int DispID, const System::AnsiString Value);

Description

Use SetPropDisplayString to set the display string for an interface for the ActiveX control.

DispID is the identifier for the interface. For more information, search the OLE.HLP file for DISPID.

Value is the new display string for the interface.


TOleControl::ShowAboutBox

TOleControl

ShowAboutBox notifies the ActiveX control to display its About box.

void __fastcall ShowAboutBox(void);

Description

Use ShowAboutBox to notify the ActiveX control to display its About box.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TOleForm

Hierarchy	Properties	Methods

TOleForm is an object that provides OLE support for a TForm object.

Unit

olectnrs

Description

TOleFrom implements the IOleForm, IOleWindow, IOleInPlaceUIWindow, and IOleInPlaceFrame interfaces, as well as a C++Builder-defined interface for internal use. The implementation of the TOleForm object is used internally by the Visual Component Library.


TOleForm properties

TOleForm	Alphabetically	Legend

Derived from TInterfacedObject

RefCount


TOleForm properties

TOleForm	By object	Legend

RefCount


TOleForm methods

TOleForm	Alphabetically

In TOleForm

~TOleForm

TOleForm

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TOleForm methods

TOleForm	By object

~TOleForm

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TOleForm


TOleForm::TOleForm

TOleForm	See also

TOleForm creates a new instance of the TOleForm object.

__fastcall TOleForm(Forms::TCustomForm* Form);

Description

TOleForm is used to create a new instance of the TOleForm object. Form is the form upon which to base the new TOleForm object.


TOleForm::~TOleForm

TOleForm	See also

~TOleForm frees the memory associated with this instance of the TOleForm object.

__fastcall virtual ~TOleForm(void);

Description

Do not call ~TOleForm directly. Instead, use the delete keyword on the object, which causes ~TOleForm to be invoked automatically.

~TOleForm frees private objects allocated and used by this instance of the TOleForm object.


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject


TOleForm example

TOleForm


TOleGraphic

Hierarchy	Properties	Methods	Events	See also

TOleGraphic is a wrapper for an OLE graphical interface.

Unit

axctrls

Description

TOleGraphic is a graphical container for icons, metafiles and bitmaps used in ActiveX controls. TOleGraphic is used internally to expose an IPicture interface as the image of the TPicture property of an ActiveX control. Because TOLEGraphic is a wrapper for OLE interfaces, it cannot be used to load or save information to a file.


TOleGraphic properties

TOleGraphic	Alphabetically	Legend

In TOleGraphic

MMHeight

MMWidth

Picture

Derived from TGraphic

Empty

Height

Modified

Palette

PaletteModified

Transparent

Width


TOleGraphic properties

TOleGraphic	By object	Legend

Empty

Height

MMHeight

MMWidth

Modified

Palette

PaletteModified

Picture

Transparent

Width


TOleGraphic::MMHeight

TOleGraphic	See also

Indicates the height of the OLE graphic in 0::01 millimeter units.

__property int MMHeight = {read=GetMMHeight, nodefault};

Description

MMHeight is used for a more accurate reading of the vertical size of the graphic. The Height property, by contrast, is always in screen device pixel units; to avoid loss of precision in converting between device pixels and millimeters, set or read the dimensions in millimeters with MMHeight.


TOleGraphic::MMWidth

TOleGraphic	See also

Indicates the width of the OLE graphic in 0::01 millimeter units.

__property int MMWidth = {read=GetMMWidth, nodefault};

Description

MMWidth is used for a more accurate reading of the horizontal size of the graphic. The Width property, by contrast, is always in screen device pixel units; to avoid loss of precision in converting between device pixels and millimeters, set or read the dimensions in millimeters with MMWidth.


TOleGraphic::Picture

TOleGraphic

Specifies the interface reference for which the OLE graphic is a container.

__property _di_IPicture Picture = {read=FPicture, write=FPicture};

Description

Picture is for internal use only.


TOleGraphic events

TOleGraphic	Alphabetically

Derived from TGraphic

OnChange

OnProgress


TOleGraphic events

TOleGraphic	By object

OnChange

OnProgress


TOleGraphic methods

TOleGraphic	Alphabetically

In TOleGraphic

~TOleGraphic

Assign

LoadFromClipboardFormat

LoadFromFile

LoadFromStream

SaveToClipboardFormat

SaveToStream

TOleGraphic

Derived from TGraphic

SaveToFile

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TOleGraphic methods

TOleGraphic	By object

~TOleGraphic

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromClipboardFormat

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

SafeCallException

SaveToClipboardFormat

SaveToFile

SaveToStream

TOleGraphic


TOleGraphic::Assign

TOleGraphic	See also

Copies an IPicture to the Ole graphic object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the IPicture contained in Source to the Ole graphic object. Assign then calls the inherited Assign. The IPicture can be a bitmap, metafile or icon image.


TOleGraphic::LoadFromClipboardFormat

TOleGraphic	See also

Loads an Ole graphic from the Clipboard into the Ole graphic object.

virtual void __fastcall LoadFromClipboardFormat(Word AFormat, int AData, HPALETTE APalette);

Description

LoadFromClipboardFormat is called if the Ole graphic is registered with the TPicture object using the RegisterClipboardFormat method.

LoadFromClipboardFormat replaces the current image with the data pointed to by the AData parameter. The palette for the Ole graphic is specified by the APalette parameter.


TOleGraphic::LoadFromFile

TOleGraphic	See also

Prevents OleGraphics from trying to load from a file.

virtual void __fastcall LoadFromFile(const System::AnsiString Filename);

Description

LoadFromFile is overriden in TOleGraphic so that it will not load a graphic from a file. Attempting to do so is not appropriate for an IPicture.


TOleGraphic::LoadFromStream

TOleGraphic	See also

Loads an IPicture interface from a stream into the OLE graphic object.

virtual void __fastcall LoadFromStream(Classes::TStream* Stream);

Description

To use LoadFromStream specify the stream from which the OLE graphic is to be loaded as the value of Stream.


TOleGraphic::SaveToClipboardFormat

TOleGraphic	See also

Saves the Ole graphic to a Clipboard format.

virtual void __fastcall SaveToClipboardFormat(Word &AFormat, int &AData, HPALETTE &APalette);

Description

Use SaveToClipboardFormat to save the Ole graphic to a Clipboard format by specifying the palette as the value of the APalette parameter, the format as the value of AFormat, and the data to be saved as the value of AData. Before the Ole graphic can be saved, an application must have registered the format with the TOleGraphic object using the RegisterClipboardFormat method.


TOleGraphic::SaveToStream

TOleGraphic	See also

Saves the Ole graphic to a stream.

virtual void __fastcall SaveToStream(Classes::TStream* Stream);

Description

Use SaveToStream to save the Ole graphic to the stream specified by the Stream parameter. SaveToStream uses the IPersistStream interface of the graphic write it to the stream.


TOleGraphic::TOleGraphic

TOleGraphic

TOleGraphic creates a new TOleGraphic object.

__fastcall virtual TOleGraphic(void) : Graphics::TGraphic() { }


TOleGraphic::~TOleGraphic

TOleGraphic

~TOleGraphic frees the memory associated with the TOleGraphic object. Do not call ~TOleGraphic directly. Instead, use the delete keyword on the object, which causes ~TOleGraphic to be invoked automatically.

__fastcall virtual ~TOleGraphic(void) { }


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TGraphic


TOleStream

Hierarchy	Properties	Methods	See also

TOleStream reads and writes information over a streaming interface that is provided by an OLE object.

Unit

axctrls

Description

Use TOleStream to create a TStream wrapper for an OLE stream interface. TOleStream uses the streaming interface of the OLE stream to read and write information. TActiveXControl objects use TOleStream to load themselves from a stream or save themselves to a stream.


TOleStream properties

TOLEStream	Alphabetically

Derived from TStream

Position

Size


TOleStream properties

TOLEStream	By object

Position

Size


TOleStream methods

TOLEStream	Alphabetically

In TOleStream

~TOLEStream

TOLEStream

Derived from TOleStream

Read

Seek

Write

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TOleStream methods

TOLEStream	By object

~TOLEStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

Seek

TOLEStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TOleStream::TOleStream

TOleStream

Creates a TOleStream object to represent a stream interface.

__fastcall TOleStream(const _di_IStream Stream);

Description

Call TOleStream to convert a stream interface into a TOleStream object. The Stream parameter is the stream interface that the TOleStream object will use for reading and writing.


TOleStream::Read

TOleStream	See also

Reads up to Count bytes from the current position into Buffer.

virtual int __fastcall Read(void *Buffer, int Count);

Description

Call Read to read data from the OLE stream when it is not known how many bytes are available. Buffer must have at least Count bytes allocated to hold the data that was read from the stream.

Read uses the stream interface to transfer up to Count bytes into Buffer, starting at the current position, and then advances the current position by the number of bytes actually transferred. Read returns the number of bytes actually transferred (which may be less than the number requested in Count::)

All the other data-reading methods of an OLE stream (ReadBuffer, ReadComponent) call Read to do their actual reading.


TOleStream::Seek

TOleStream	See also

Resets the current position of the stream.

virtual int __fastcall Seek(int Offset, Word Origin);

Description

Use Seek to move the current position by the indicated offset. Seek uses the stream interface to change the current position to the value indicated by the Offset and Origin parameters.

The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value	Meaning

soFromBeginning	Offset is from the beginning of the OLE stream. Seek moves to the position Offset. Offset must be >= 0.

soFromCurrent	Offset is from the current position in the OLE stream. Seek moves to Position + Offset.

soFromEnd	Offset is from the end of the OLE stream. Offset must be <= 0 to indicate a number of bytes before the end of the stream.

Seek returns the new value of the Position property.


TOleStream::Write

TOleStream	See also

Writes Count bytes from Buffer to the current position in the OLE stream and updates the current position by Count bytes.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Use Write to write Count bytes to the OLE stream, starting at the current position. Write uses the stream interface to transfer the information from Buffer.

All the other data-writing methods of an OLE stream (WriteBuffer, WriteComponent) call Write to do their actual writing.


TOleStream::~TOleStream

TOLEStream

~TOleStream frees the memory associated with the TOleStream object. Do not call ~TOleStream directly. Instead, use the delete keyword on the object, which causes ~TOleStream to be invoked automatically.

__fastcall virtual ~TOleStream(void) { }


Hierarchy

TObject

TStream


 TOpenDialog

Hierarchy	Properties	Methods	Events	See also

TOpenDialog displays a file-selection dialog.

Unit

dialogs

Description

TOpenDialog displays a modal Windows dialog box for selecting and opening files. The dialog does not appear at runtime until it is activated by a call to the Execute method. When the user clicks Open, the dialog closes and the selected file or files are stored in the Files property.


TOpenDialog properties

TOpenDialog	Alphabetically	Legend

In TOpenDialog

DefaultExt

FileEditStyle

FileName

Files

Filter

FilterIndex

HistoryList

InitialDir

Options

Title

Derived from TCommonDialog

Ctl3D

Handle

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TOpenDialog properties

TOpenDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DefaultExt

DesignInfo

FileEditStyle

FileName

Files

Filter

FilterIndex

Handle

HelpContext

HistoryList

InitialDir

Name

Options

Owner

Tag

Title

VCLComObject


TOpenDialog::DefaultExt

TOpenDialog 	Example

Specifies a default file extension.

__property System::AnsiString DefaultExt = {read=FDefaultExt, write=FDefaultExt};

Description

DefaultExt specifies a file extension that is appended automatically to the selected file name, unless the selected file name already includes a registered extension. If the user selects a file name with an extension that is unregistered, DefaultExt is appended to the unregistered extension.

Extensions longer than three characters are not supported. Do not include the period (.) that divides the file name and its extension.


TOpenDialog::FileEditStyle

TOpenDialog

Determines the style of the file-selection dialog. (Obsolete.)

enum TFileEditStyle { fsEdit, fsComboBox };

__property TFileEditStyle FileEditStyle = {read=FFileEditStyle, write=FFileEditStyle, nodefault};

Description

FileEditStyle is maintained for compatibility with older versions of the VCL.


TOpenDialog::FileName

TOpenDialog	See also 	Example

Indicates the name and directory path of the last file selected.

__property System::AnsiString FileName = {read=GetFileName, write=FFileName};

Description

The FileName property returns the name and complete directory path of the most recently selected file. The value of FileName is the same as the first item in the Files property.

To make a file name appear by default in the dialog’s edit box, assign a value to FileName in the Object Inspector or in program code. Programmatic changes to FileName have no effect while the dialog is active.


TOpenDialog::Files

TOpenDialog	See also 	Example

Returns a list of the selected file names.

__property Classes::TStrings* Files = {read=FFiles};

Description

FileName is a TStrings instance that contains each selected file name with its full directory path. (To let users select multiple file names, set the ofAllowMultiSelect flag in Options.)


TOpenDialog::Filter

TOpenDialog	See also 	Example

Determines the file masks (filters) available in the dialog.

__property System::AnsiString Filter = {read=FFilter, write=FFilter};

Description

The file-selection dialog includes a drop-down list of file types under the edit box. When the user picks a file type from the list, only files of the selected type are displayed in the dialog.

To configure file masks at design time, click on the ellipsis marks (...) to the right of the Filter property in the Object Inspector. This opens the Filter editor. In the left column of the Filter editor, under Filter Name, type a brief description of each file type that will be available at runtime. In the right column, under Filter, type the file mask corresponding to each description. For example, the description “Text files” might appear to the left of the mask “*.TXT”, and the description “Pascal source files” might appear to the left of the mask “*.PAS”. Since the description appears in the drop-down list at runtime, it is often helpful to show the mask explicitly in the description (for example, “Text files (*.txt)”).

To create file masks in program code, assign a value to the Filter property that consists of a description and a mask separated by a vertical bar (pipe) character. Do not include spaces around the vertical bar. For example,

OpenDialog1->Filter = "Text files (*.txt)|*.TXT";

Multiple filters should be separated by vertical bars. For example,

OpenDialog1->Filter = "Text files (*.txt)|*.TXT|Pascal files (*.pas)|*.PAS";

To include multiple masks in a single filter, separate the masks with semicolons. This works both in the Object Inspector and in program code. For example,

OpenDialog1->Filter = "Pascal files|*.PAS;*.DPK;*.DPR";

If no value is assigned to Filter, the dialog displays all file types.


TOpenDialog::FilterIndex

TOpenDialog	See also 	Example

Determines which filter is selected by default when the dialog opens.

__property int FilterIndex = {read=GetFilterIndex, write=FFilterIndex, default=1};

Description

FilterIndex determines which of the file types in Filter is selected by default when the dialog opens. Set FilterIndex to 1 to choose the first file type in the list as the default, or set FilterIndex to 2 to choose the second file type as the default, and so forth. If the value of FilterIndex is out or range, the first file type listed in Filter is the default.


TOpenDialog::HistoryList

TOpenDialog	See also

Maintains a list of previously selected files. (Obsolete::)

__property Classes::TStrings* HistoryList = {read=FHistoryList, write=SetHistoryList};

Description

HistoryList is maintained for compatibility with older versions of the VCL.


TOpenDialog::InitialDir

TOpenDialog

Determines the current directory when the dialog opens.

__property System::AnsiString InitialDir = {read=FInitialDir, write=SetInitialDir};

Description

InitialDir determines the default directory displayed in the file-selection dialog when it opens. For example, to point the dialog at the WINDOWS\SYSTEM directory, set the value of InitialDir to C:\WINDOWS\SYSTEM.

If no value is assigned to InitialDir, or if the specified directory does not exist, the dialog opens with the current working directory displayed.


TOpenDialog::Options

TOpenDialog	See also 	Example

Determines the appearance and behavior of the file-selection dialog.

enum TOpenOption { ofReadOnly, ofOverwritePrompt, ofHideReadOnly, ofNoChangeDir, ofShowHelp, ofNoValidate, ofAllowMultiSelect, ofExtensionDifferent, ofPathMustExist, ofFileMustExist, ofCreatePrompt, ofShareAware, ofNoReadOnlyReturn, ofNoTestFileCreate, ofNoNetworkButton, ofNoLongNames, ofOldStyleDialog, ofNoDereferenceLinks };

typedef Set<TOpenOption, ofReadOnly, ofNoDereferenceLinks>  TOpenOptions;

__property TOpenOptions Options = {read=FOptions, write=FOptions, default=4};

Description

Use the Options property to customize the appearance and functionality of the dialog. The possible values of Options are

Value	Meaning

ofAllowMultiSelect	Allows users to select more than one file in the dialog.

ofCreatePrompt	Generates a warning message if the user tries to select a nonexistent file, asking whether to create a new file with the specified name.

ofExtensionDifferent	This flag is turned on at runtime whenever the selected filename has an extension that differs from DefaultExt. If you use this flag an application, remember to reset it.

ofFileMustExist	Generates an error message if the user tries to select a nonexistent file.

ofHideReadOnly	Removes the Open As Read Only check box from the dialog.

ofNoChangeDir	After the user clicks OK, resets the current directory to whatever it was before the file-selection dialog opened.

ofNoDereferenceLinks	Disables dereferencing of Windows shortcuts. If the user selects a shortcut, assigns to FileName the path and file name of the shortcut itself (the .LNK file), rather than the file linked to the shortcut.

ofNoLongNames	Displays 8.3-character file names only.

ofNoNetworkButton	Removes the Network button (which opens a Map Network Drive dialog) from the file-selection dialog. Applies only if the ofOldStyleDialog flag is on.

ofNoReadOnlyReturn	Generates an error message if the user tries to select a read-only file.

ofNoTestFileCreate	Disables checking for network file protection and inaccessibility of disk drives. Applies only when the user tries to save a file in a create-no-modify shared network directory.

ofNoValidate	Disables checking for invalid characters in file names. Allows selection of file names with invalid characters.

ofOldStyleDialog	Creates the older style of file-selection dialog.

ofOverwritePrompt	Generates a warning message if the user tries to select a file name that is already in use, asking whether to overwrite the existing file. (Use with TSaveDialog and TSavePictureDialog.)

ofPathMustExist	Generates an error message if the user tries to select a file name with a nonexistent directory path.

ofReadOnly	Selects the Open As Read Only check box by default when the dialog opens.

ofShareAware	Ignores sharing errors and allows files to be selected even when sharing violations occur.

ofShowHelp	Displays a Help button in the dialog.

By default, all options flags are off.


TOpenDialog::Title

TOpenDialog 	Example

Specifies the text in the dialog’s title bar.

__property System::AnsiString Title = {read=FTitle, write=FTitle};

Description

Use Title to specify the text that appears in the file-selection dialog’s title bar. If no value is assigned to Title, the dialog has the title “Open”.


TOpenDialog events

TOpenDialog	Alphabetically	Legend

In TOpenDialog

OnCanClose

OnFolderChange

OnSelectionChange

OnTypeChange

Derived from TCommonDialog

OnClose

OnShow


TOpenDialog events

TOpenDialog	By object	Legend

OnCanClose

OnClose

OnFolderChange

OnSelectionChange

OnShow

OnTypeChange


TOpenDialog::OnCanClose

TOpenDialog 	See also

Occurs when the user tries to close the dialog without canceling.

typedef void __fastcall (__closure *TCloseQueryEvent)(System::TObject* Sender, bool &CanClose);

__property TCloseQueryEvent OnCanClose = {read=FOnCanClose, write=FOnCanClose };

Description

Write an OnCanClose event handler to provide custom validation of the value of FileName. File selection dialogs provide a number of built-in validations, such as checking for invalid characters, prompting for confirmation before overwriting, checking whether a file or path exists, and so on. These validations can be specified using the Options property. However, applications can provide additional validation of file names in an OnCanClose event handler.

Set the CanClose parameter to false to prevent the dialog from closing. The OnCanClose event handler is responsible for telling the user why the dialog doesn’t close.

Note:	OnCanClose does not occur under Windows NT 3.51 unless the new shell is installed.


TOpenDialog::OnFolderChange

TOpenDialog

Occurs when a directory is opened or closed from the dialog.

__property Classes::TNotifyEvent OnFolderChange = {read=FOnFolderChange, write=FOnFolderChange};

Description

The OnFolderChange event occurs when the user changes the directory whose contents are displayed in the dialog. This can happen when the user double-clicks on a directory, clicks the Up arrow, or uses the list box at the top of the dialog to navigate through the directory structure.


TOpenDialog::OnSelectionChange

TOpenDialog	See also

Occurs when file names displayed in the dialog are changed.

__property Classes::TNotifyEvent OnSelectionChange = {read=FOnSelectionChange, write=FOnSelectionChange};

Description

The OnSelectionChange event occurs when the user does something to change the list displayed in the dialog. This can include opening the file-selection dialog, highlighting a file or directory, selecting a new filter, selecting a new directory, or creating a new folder.


TOpenDialog::OnTypeChange

TOpenDialog	See also

Occurs when the file types displayed in the dialog are changed.

__property Classes::TNotifyEvent OnTypeChange = {read=FOnTypeChange, write=FOnTypeChange};

Description

The OnTypeChange event occurs when the user selects a new filter from the Files of Type list box at the bottom of the dialog.


TOpenDialog methods

TOpenDialog	Alphabetically	Legend

In TOpenDialog

~TOpenDialog

Execute

GetStaticRect

TOpenDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TOpenDialog methods

TOpenDialog	By object	Legend

~TOpenDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetStaticRect

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TOpenDialog


TOpenDialog::TOpenDialog

TOpenDialog	See also

Creates and initializes a TOpenDialog instance.

__fastcall virtual TOpenDialog(Classes::TComponent* AOwner);

Description

Do not call TOpenDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.

The TOpenDialog method generates a TOpenDialog instance, but the new dialog does not appear on the form at runtime until the Execute method is called.


TOpenDialog::~TOpenDialog

TOpenDialog	See also

Destroys the TOpenDialog and frees its memory.

__fastcall virtual ~TOpenDialog(void);

Description

Do not call ~TOpenDialog directly. Instead, use the delete keyword on the object, which causes ~TOpenDialog to be invoked automatically.


TOpenDialog::Execute

TOpenDialog 	Example

Displays the file-selection dialog.

virtual bool __fastcall Execute(void);

Description

Execute opens the file-selection dialog, returning true when the user selects a file and clicks Open. If the user clicks Cancel, Execute returns false.


TOpenDialog::GetStaticRect

TOpenDialog	See also

Returns the coordinates of the reserved area of the dialog box.

virtual Windows::TRect __fastcall GetStaticRect();

Description

GetStaticRect is provided for components that descend from TOpenDialog and require the placement of new controls alongside the standard ones inherited from the parent class. For Explorer-style dialogs (running under Windows 95 or NT 4.0), GetStaticRect returns the size and location of the standard controls within the dialog. For older versions of Windows, or if ofOldStyleDialog is enabled in Options, GetStaticRect returns the client dimensions of the entire dialog box.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog


 TOpenPictureDialog

Hierarchy	Properties	Methods	Events	See also

TOpenPictureDialog displays a graphics-file selection dialog.

Unit

extdlgs

Description

TOpenPictureDialog displays a modal Windows dialog box for selecting and opening graphics files. This component is just like TOpenDialog, except that it includes a rectangular preview region. If the selected image can be read by TPicture, it is displayed in the preview region; supported file types include bitmap (.BMP), icon (.ICO), Windows metafile (.WMF), and enhanced Windows metafile (.EMF). If the selected image cannot be displayed, “(None)” appears in the preview region.

If the user selects a file of an unrecognized type, TPicture throws an EInvalidGraphic exception.


TOpenPictureDialog properties

TOpenPictureDialog	Alphabetically	Legend

Derived from TOpenDialog

DefaultExt

FileEditStyle

FileName

Files

Filter

FilterIndex

HistoryList

InitialDir

Options

Title

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TOpenPictureDialog properties

TOpenPictureDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DefaultExt

DesignInfo

FileEditStyle

FileName

Files

Filter

FilterIndex

HelpContext

HistoryList

InitialDir

Name

Options

Owner

Tag

Title

VCLComObject


TOpenPictureDialog events

TOpenPictureDialog	Alphabetically	Legend

Derived from TOpenDialog

OnCanClose

OnSelectionChange

Derived from TCommonDialog

OnClose

OnShow


TOpenPictureDialog events

TOpenPictureDialog	By object	Legend

OnCanClose

OnClose

OnSelectionChange

OnShow


TOpenPictureDialog methods

TOpenPictureDialog	Alphabetically

In TOpenPictureDialog

~TOpenPictureDialog

Execute

TOpenPictureDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TOpenPictureDialog methods

TOpenPictureDialog	By object

~TOpenPictureDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TOpenPictureDialog


TOpenPictureDialog::TOpenPictureDialog

TOpenPictureDialog	See also 	Example

Creates and initializes a TOpenPictureDialog instance.

__fastcall virtual TOpenPictureDialog(Classes::TComponent* AOwner);

Description

Do not call TOpenPictureDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.

The TOpenPictureDialog method generates a TOpenPictureDialog instance, but the dialog does not appear at runtime until the Execute method is called. TOpenPictureDialog initializes the Filter property by defining a filter for each file type that TPicture supports.


TOpenPictureDialog::~TOpenPictureDialog

TOpenPictureDialog	See also

Destroys the TOpenPictureDialog and frees its memory.

__fastcall virtual ~TOpenPictureDialog(void);

Description

Do not call ~TOpenDialog directly. Instead, use the delete keyword on the object, which causes ~TOpenDialog to be invoked automatically.


TOpenPictureDialog::Execute

TOpenPictureDialog

Displays the file-selection dialog.

virtual bool __fastcall Execute(void);

Description

Execute opens the file-selection dialog, returning true when the user selects a file and clicks Open. If the user clicks Cancel, Execute returns false.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog

TOpenDialog


OutlineError

Hierarchy	Methods	See also

OutlineError is a special exception class for invalid outline-node indexes.

Unit

outline

Description

OutlineError is thrown when an application cannot access a specified outline node. In most cases, this occurs because the index used is invalid.

OutlineError is thrown internally to abort look-ups of outline components. Because it does not descend from Exception, it never appears at runtime—even if the debugger is set to break on exceptions. Thus it is a useful tool for aborting deep recursions.

Note

OutlineError is thrown by the TOutline component, which is maintained for compatibility with older versions of the VCL only.


OutlineError methods

OutlineError	Alphabetically

In OutlineError

~OutlineError

OutlineError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


OutlineError methods

OutlineError	By object

~OutlineError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

OutlineError

SafeCallException


OutlineError::OutlineError

OutlineError

OutlineError creates a new OutlineError object.

__fastcall OutlineError(void) : System::TObject() { }

Description

Do not call OutlineError directly. Instead, use the keyword new, which returns an indirect reference to the new OutlineError object.


OutlineError::~OutlineError

OutlineError

~OutlineError frees the memory associated with the OutlineError object.

__fastcall virtual ~OutlineError(void) { }

Description

Do not call ~OutlineError directly. Instead, use the delete keyword on the object, which causes ~OutlineError to be invoked automatically.


Hierarchy

TObject


OutlineError example

OutlineError


TOwnedCollection

Hierarchy	Properties	Methods	See also

TOwnedCollection is a collection that maintains information about its owner.

Unit

classes

Description

TOwnedCollection is a collection that maintains information about its owner. This lets the Object Inspector display the collection's name at design time.

New collection classes should descend from TOwnedCollection. Classes that descend directly from TCollection must implement a GetOwner method if they are to appear in the Object Inspector.


TOwnedCollection properties

TOwnedCollection	Alphabetically	Legend

Derived from TCollection

Count

ItemClass

Items


TOwnedCollection properties

TOwnedCollection	By object	Legend

Count

ItemClass

Items


TOwnedCollection methods

TOwnedCollection	Alphabetically

In TOwnedCollection

~TOwnedCollection

TOwnedCollection

Derived from TCollection

Add

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TOwnedCollection methods

TOwnedCollection	By object

~TOwnedCollection

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TOwnedCollection


TOwnedCollection::TOwnedCollection

TOwnedCollection	See also

Creates and initializes a TOwnedCollection instance.

__fastcall TOwnedCollection(TPersistent* AOwner, System::TMetaClass* ItemClass);

Description

The TOwnedCollection method takes two parameters: the name of an instance object descended from TPersistent and the name of a TCollectionItem descendant class. The first parameter is the owner of the TOwnedCollection instance. The second parameter determines the class of the items created by the Add method.


TOwnedCollection::~TOwnedCollection

TOwnedCollection

~TOwnedCollection frees the memory associated with the TOwnedCollection object.

__fastcall virtual ~TOwnedCollection(void) { }

Description

Do not call ~TOwnedCollection directly. Instead, use the delete keyword on the object, which causes ~TOwnedCollection to be invoked automatically.

~TOwnedCollection calls the Clear method to free each item referenced in the Items array, then destroys the collection itself.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


 TPageControl

Hierarchy	Properties	Methods	Events	See also

TPageControl is a set of pages used to make a multiple page dialog box.

Unit

comctrls

Description

Use TPageControl to create a multiple page dialog or tabbed notebook. TPageControl displays multiple overlapping pages which are TTabSheet objects. The user selects a page by clicking the page’s tab that appears at the top of the control. To add a new page to a TPageControl object at design time, right-click the TPageControl object and choose New Page.

To create a tabbed control that uses only a single body portion (page), use TTabControl instead.


TPageControl properties

TPageControl	Alphabetically	Legend

In TPageControl

ActivePage

PageCount

Pages

Derived from TCustomTabControl

HotTrack

MultiLine

ScrollOpposite

TabHeight

TabPosition

TabWidth

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TPageControl properties

TPageControl	By object	Legend

ActivePage

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

HotTrack

Left

MultiLine

Name

Owner

PageCount

Pages

Parent

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ScrollOpposite

ShowHint

Showing

TabHeight

TabOrder

TabPosition

TabStop

TabWidth

Tag

Top

VCLComObject

Visible

Width

WindowProc


TPageControl::ActivePage

TPageControl	See also	Example

Specifies the page currently displayed by the page control.

__property TTabSheet* ActivePage = {read=FActivePage, write=SetActivePage};

Description

Read ActivePage to determine which page is selected by the user. The user selects a page by clicking the mouse on its tab. Set ActivePage to bring a page to the foreground. Only one page can be active at a time.

To change the ActivePage to the page that precedes or follows the active page, use the SelectNextPage method. To iterate through all the pages to locate a specific page, use the FindNextPage method.


TPageControl::PageCount

TPageControl	See also	Example

Indicates the number of pages in the TPageControl object.

__property int PageCount = {read=GetPageCount, nodefault};

Description

Use PageCount to determine the number of pages listed by the Pages property. If the MultiLine property is false, not all pages may have tabs visible to the user.


TPageControl::Pages

TPageControl	See also	Example

Lists all the pages in the TPageControl.

__property TTabSheet* Pages[int Index] = {read=GetPage};

Description

Use Pages to gain direct access to a particular page in the page control. For example, use Pages to disable individual pages in the page control. Specify which page to access using Index, where an Index of 0 specifies the first page, an Index of 1 specifies the second page, and so on. Each page is a TTabSheet object.

To locate a page in the page control by its position relative to another page, use the FindNextPage method.


TPageControl events

TPageControl	Alphabetically	Legend

Derived from TCustomTabControl

OnChange

OnChanging

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TPageControl events

TPageControl	By object	Legend

OnChange

OnChanging

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TPageControl methods

TPageControl	Alphabetically

In TPageControl

~TPageControl

FindNextPage

SelectNextPage

TPageControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPageControl methods

TPageControl	By object

~TPageControl

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

FindNextPage

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectNextPage

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TPageControl

Update

UpdateControlState


TPageControl::TPageControl

TPageControl	See also

Creates an instance of PageControl.

__fastcall virtual TPageControl(Classes::TComponent* AOwner);

__fastcall TPageControl(HWND ParentWindow) : Comctrls::TCustomTabControl(ParentWindow) { }

Description

Call TPageControl indirectly, using the new keyword, to instantiate a page control at runtime. Page controls added to forms at design time are created automatically.

Pass a single Component as a parameter to provide the page control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the page control in a non-VCL window. This syntax is used when the page control control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent class’s constructor, TPageControl sets ControlStyle to csDoubleClicks, and creates a TList object to hold the pages of the control.

When creating a page control at runtime, the pages must be added programmatically. To add a page to a page control at runtime, create the TTabSheet object for the page and set its PageControl property.


TPageControl::~TPageControl

TPageControl	See also

Destroys an instance of TPageControl.

__fastcall virtual ~TPageControl(void);

Description

Do not call ~TPageControl directly in an application. Instead, use the delete keyword. ~TPageControl frees the TList object that holds the pages of the control, and then calls the parent object’s destructor.


TPageControl::FindNextPage

TPageControl	See also	Example

Returns the next page in the page control before or after a specified page.

TTabSheet* __fastcall FindNextPage(TTabSheet* CurPage, bool GoForward, bool CheckTabVisible);

Description

Call FindNextPage to locate a page in the page control by its position relative to the page specified by the CurPage parameter. If the GoForward parameter is true, FindNextPage returns the next page in the page control after CurPage. If GoForward is false, FindNextPage returns the previous page. If CurPage is not a page in the page control, FindNextPage returns the first page when GoForward is true or the last page when GoForward is false. If GoForward is true and CurPage is the last page in the page control, FindNextPage returns the first page. If GoForward is false and CurPage is the first page in the page control, FindNextPage returns the last page.

When CheckTabVisible is true, FindNextPage returns the next page with a TabVisible property set to true; if CheckTabVisible is false, FindNextPage returns the next page, including pages with TabVisible set to false.


TPageControl::SelectNextPage

TPageControl	See also	Example

Changes the ActivePage to the first visible page that is before or after the currently active page.

void __fastcall SelectNextPage(bool GoForward);

Description

Use SelectNextPage to select the page next to the currently active page. If the GoForward parameter is true, SelectNextPage selects the first page after ActivePage; if GoForward is false, SelectNextPage selects the first page previous to ActivePage. SelectNextPage will only considers pages with their TabVisible property set to true.

Note:	To select a page at design-time, right-click the TPageControl and choose Previous Page or Next Page.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomTabControl


 TPageProducer

Hierarchy	Properties	Methods	Events	See also

TPageProducer produces a string of HTML commands based on an input template.

Unit

httpapp

Description

Use TPageProducer to convert an HTML template into a string of HTML commands that can be interpreted by a client application such as a Web browser. HTML templates include HTML commands and HTML-transparent tags that are replaced with customized content by the OnHTMLTag event.

Note:	See the WebServ demo for an example of how to use TPageProducer.


TPageProducer properties

TPageProducer	Alphabetically	Legend

Derived from TCustomPageProducer

HTMLDoc

HTMLFile

Derived from TCustomContentProducer

Dispatcher

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TPageProducer properties

TPageProducer	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Dispatcher

HTMLDoc

HTMLFile

Name

Owner

Tag

VCLComObject


TPageProducer events

TPageProducer	Alphabetically	Legend

In TPageProducer

OnHTMLTag


TPageProducer events

TPageProducer	By object	Legend

OnHTMLTag


TPageProducer::OnHTMLTag

TPageProducer	See also 	Example

Occurs when the page producer needs to interpret the value of an HTML-transparent tag in the HTML template.

enum TTag { tgCustom, tgLink, tgImage, tgTable, tgImageMap, tgObject, tgEmbed };

typedef void __fastcall (__closure *THTMLTagEvent)(System::TObject* Sender, TTag Tag, const System::AnsiString TagString, Classes::TStrings* TagParams, System::AnsiString &ReplaceText);

__property THTMLTagEvent OnHTMLTag = {read=FOnHTMLTag, write=FOnHTMLTag};

Description

Write an OnHTMLTag event handler to convert an HTML-transparent tag into the corresponding HTML commands that can be interpreted by a Web browser. If an OnHTMLTag event is not supplied, the HTML-transparent tags in the HTML template will be replaced by empty strings.

The Tag parameter indicates the type of HTML-transparent tag that was encountered in the HTML template. It can have one of the following values

Value	Meaning

tgLink	The TagString parameter is LINK. The TagParams describe a hypertext link. The event handler should return a sequence of HTML commands beginning with an <A> tag and ending with an </A> tag.

tgImage	The TagString parameter is IMAGE. The TagParams describe a graphic image. The event handler should return an HTML <IMG> tag.

tgTable	The TagString parameter is TABLE. The TagParams describe a desired tabular image. The event handler should return a sequence of HTML commands beginning with a <TABLE> tag and ending with a </TABLE> tag.

tgImageMap	The TagString parameter is IMAGEMAP. The TagParams describe a graphic image with associated hotzones. The event handler should return a sequence of HTML commands beginning with a <MAP> tag and ending with a </MAP> tag.

tgObject	The TagString parameter is OBJECT. The TagParams contain a reference to an ActiveX control. The event handler should return a sequence of HTML commands beginning with an <OBJECT> tag and ending with an </OBJECT> tag.

tgEmbed	The TagString parameter is EMBED. The TagParams contain a reference to a Netscape-compliant add-in DLL. The event handler should return a sequence of HTML commands beginning with an <EMBED> tag and ending with an </EMBED> tag.

tgCustom	The TagString parameter is an application-defined string. The event handler can convert the HTML-transparent tag in an application-specific manner.

The TagString parameter is the tag name of the HTML-transparent tag. If the Tag parameter is tgCustom, TagString should be used to determine what conversion to perform. The TagParams parameter gives the parameter portion of the HTML-transparent tag. Each string in the TStrings object has the form ParamName=Value. Use the Names and Values properties of the TStrings object to parse these parameters.

The OnHTMLTag event handler should return the converted HTML commands in the ReplaceText parameter. The returned value can contain HTML-transparent tags for another page producer to convert. For example, one page producer might have a template that represents the format of the final HTTP response. It could read the HTTP request and for each section in the request assemble a set of HTML-transparent tags with parameters based on the request. Another page producer might take the content of the first page producer, and interpret those parameters.


TPageProducer methods

TPageProducer	Alphabetically

In TPageProducer

~TPageProducer

TPageProducer

Derived from TCustomPageProducer

Content

ContentFromStream

ContentFromString

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPageProducer methods

TPageProducer	By object

~TPageProducer

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Content

ContentFromStream

ContentFromString

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TPageProducer


TPageProducer::TPageProducer

TPageProducer

Creates a new TPageProducer object.

__fastcall virtual TPageProducer(Classes::TComponent* AOwner) : Httpapp::TCustomPageProducer(AOwner) { }

Description

Do not call TPageProducer directly in an application. Instead, use the new keyword to create a page producer component at runtime, passing as an argument an Owner component that is responsible for freeing the page producer. Page producers placed in Web modules at design time are created automatically.


TPageProducer::~TPageProducer

TPageProducer

Frees the memory associated with the TPageProducer object.

__fastcall virtual ~TPageProducer(void) { }

Description

Do not call ~TPageProducer directly. Instead, use the delete keyword on the object, which causes ~TPageProducer to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomContentProducer

TCustomPageProducer


 TPaintBox

Hierarchy	Properties	Methods	Events	See also

TPaintBox is a simple graphic control that provides a canvas for applications to use for rendering an image.

Unit

extctrls

Description

Use TPaintBox to add custom images to a form. Unlike TImage, which displays an image that is stored in a bitmap, icon, or metafile, TPaintBox requires an application to draw the image directly on a canvas. Use the OnPaint event handler to draw on the paint box’s Canvas, the drawing surface of the paint box.


TPaintBox properties

TPaintBox	Alphabetically	Legend

Derived from TGraphicControl

Canvas

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TPaintBox properties

TPaintBox	By object	Legend

Align

BoundsRect

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Tag

Top

VCLComObject

Visible

Width

WindowProc


TPaintBox events

TPaintBox	Alphabetically	Legend

In TPaintBox

OnPaint

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TPaintBox events

TPaintBox	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnStartDrag


TPaintBox::OnPaint

TPaintBox	See also 	Example

OnPaint occurs when the paintbox receives a Windows paint message.

__property Classes::TNotifyEvent OnPaint = {read=FOnPaint, write=FOnPaint};

Description

Write an OnPaint event handler to draw the image of the paint box. Use the methods of the canvas to construct the image that the paintbox presents on a form. If an OnPaint event handler is not provided, the paintbox can’t be seen on the form at runtime.


TPaintBox methods

TPaintBox	Alphabetically	Legend

In TPaintBox

~TPaintBox

Paint

TPaintBox

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPaintBox methods

TPaintBox	By object	Legend

~TPaintBox

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Paint

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TPaintBox

Update


TPaintBox::TPaintBox

TPaintBox	See also

Creates an instance of TPaintBox.

__fastcall virtual TPaintBox(Classes::TComponent* AOwner);

Description

Do not call TPaintBox directly. Instead, use the keyword new, which returns an indirect reference to the new TPaintBox object. TPaintBox objects added to forms at design time are created automatically.

TPaintBox allocates memory and sets the default values for the instance of the TPaintBox object.


TPaintBox::Paint

TPaintBox	See also

Generates an OnPaint event.

virtual void __fastcall Paint(void);

Description

Paint responds to WM_PAINT messages from Windows by initializing the canvas and calling the OnPaint event handler if it is assigned.


TPaintBox::~TPaintBox

TPaintBox

~TPaintBox frees the memory associated with the TPaintBox object.

__fastcall virtual ~TPaintBox(void) { }

Do not call ~TPaintBox directly. Instead, use the delete keyword on the object, which causes ~TPaintBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


TPaintControl

Hierarchy	Properties	Methods	See also

TPaintControl draws data aware controls that are replicated in a data control grid.

Unit

dbctrls

Description

Several data-aware controls use TPaintControl — including TDBCheckBox, TDBComboBox, and TDBMemo—to replicate themselves within a data control grid (TDBCtrlGrid).


TPaintControl properties

TPaintControl	Alphabetically	Legend

In TPaintControl

Ctl3DButton

Handle


TPaintControl properties

TPaintControl	By object	Legend

Ctl3DButton

Handle


TPaintControl::Ctl3DButton

TPaintControl

Determines whether the control has a three-dimensional look.

__property bool Ctl3DButton = {read=FCtl3dButton, write=SetCtl3DButton, nodefault};

Description

If Ctl3DButton is true, the data-aware control has beveled borders, creating a three-dimensional appearance.


TPaintControl::Handle

TPaintControl 	See also

Provides access to paint control’s window handle.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Handle is the window handle of the TPaintControl instance. It represents a window with the classname supplied to the constructor of the TPaintControl object.  The characteristics of the window are determined by the Owner supplied to the constructor of the paint control object.


TPaintControl methods

TPaintControl	Alphabetically

In TPaintControl

~TPaintControl

DestroyHandle

TPaintControl

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPaintControl methods

TPaintControl	By object

~TPaintControl

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyHandle

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TPaintControl


TPaintControl::TPaintControl

TPaintControl 	See also

Creates and initializes a TPaintControl object.

__fastcall TPaintControl(Controls::TWinControl* AOwner, const System::AnsiString ClassName);

Description

Call TPaintControl indirectly, using the new keyword, to create an instance of TPaintControl.  The Owner parameter specifies the data-aware control that uses this TPaintControl object to paint its image.  The ClassName parameter specifies the Window class that should be created by the paint control.


TPaintControl::~TPaintControl

TPaintControl	See also

Destroys the TPaintControl and frees its memory.

__fastcall virtual ~TPaintControl(void);

Description

Do not call ~TPaintControl directly in an application. Instead, use the delete keyword.

~TPaintControl frees the window used by the paint control.


TPaintControl::~TPaintControl
TPaintControl::DestroyHandle

TPaintControl	See also

Destroys the window used by the paint control.

void __fastcall DestroyHandle(void);

Description

The destructor of TPaintControl calls DestroyHandle to release the Windows resources allocated on behalf of the paint control.


Accessibility

Read-only


Hierarchy

TObject


 TPanel

Hierarchy	Properties	Methods	Events	See also

TPanel implements a generic panel control.

Unit

extctrls

Description

Use TPanel to put an empty panel on a form. Panels provide properties for providing a bevelled border around the control, as well as methods to help manage the placement of child controls embedded in the panel.

TPanel implements the generic behavior introduced in TCustomPanel. TPanel publishes many of the properties inherited from TCustomPanel, but does not introduce any new behavior.


TPanel properties

TPanel	Alphabetically	Legend

Derived from TCustomPanel

Alignment

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

FullRepaint

Locked

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TPanel properties

TPanel	By object	Legend

Align

Alignment

BevelInner

BevelOuter

BevelWidth

BorderStyle

BorderWidth

BoundsRect

Brush

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

FullRepaint

Handle

Height

HelpContext

Hint

Left

Locked

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TPanel events

TPanel	Alphabetically	Legend

Derived from TCustomPanel

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TPanel events

TPanel	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnStartDrag


TPanel methods

TPanel	Alphabetically

In TPanel

~TPanel

TPanel

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPanel methods

TPanel	By object

~TPanel

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TPanel

Update

UpdateControlState


TPanel::TPanel

TPanel

Creates a new TPanel object.

__fastcall virtual TPanel(Classes::TComponent* AOwner) : Extctrls::TCustomPanel(AOwner) { }

__fastcall TPanel(HWND ParentWindow) : Extctrls::TCustomPanel(ParentWindow) { }

Description

Do not call TPanel directly when creating a panel at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created panel. TPanel objects placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the panel with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the panel in a non-VCL window. This syntax is used when the panel is implemented as an ActiveX control that is embedded in a non-VCL window.


TPanel::~TPanel

TPanel

Frees the memory associated with the TPanel object.

__fastcall virtual ~TPanel(void) { }

Description

Do not call ~TPanel directly. Instead, use the delete keyword on the object, which causes ~TPanel to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomPanel


TParaAttributes

Hierarchy	Properties	Methods	See also

TParaAttributes represents paragraph formatting properties for a rich edit control.

Unit

comctrls

Description

TParaAttributes includes a number of properties that describe the formatting characteristics of a paragraph in a rich text document. TParaAttributes is tailored to allow a descendant of TCustomRichEdit to read and write formatting characteristics of selected paragraphs. The properties of a TParaAttributes object are invalid unless it is owned by a descendant of TCustomRichEdit.


TParaAttributes properties

TParaAttributes	Alphabetically

In TParaAttributes

Alignment

FirstIndent

LeftIndent

Numbering

RightIndent

Tab

TabCount


TParaAttributes properties

TParaAttributes	By object

Alignment

FirstIndent

LeftIndent

Numbering

RightIndent

Tab

TabCount


TParaAttributes::Alignment

TParaAttributes	See also 	Example

Specifies how text is aligned within a paragraph.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=GetAlignment, write=SetAlignment, nodefault};

Description

Use Alignment to specify the alignment of text within individual paragraphs. Unlike the Alignment property of a TCustomMemo, which applies to the entire body of text, the Alignment property of TParaAttributes applies only to the selected paragraphs.

These are the possible values:

Value	Meaning

taLeftJustify	Align text to the left side of the paragraph.

taCenter	Center text horizontally in the paragraph.

taRightJustify	Align text to the right side of the paragraph.


TParaAttributes::FirstIndent

TParaAttributes	See also 	Example

Specifies the indent, in pixels, of the first line of the paragraph relative to the left margin.

__property int FirstIndent = {read=GetFirstIndent, write=SetFirstIndent, nodefault};

Description

Use FirstIndent to specify the number of pixels to indent the first line of the paragraph. This value is relative to the value of LeftIndent.


TParaAttributes::LeftIndent

TParaAttributes	See also

Specifies the indent, in pixels, of the paragraph relative to the left margin.

__property int LeftIndent = {read=GetLeftIndent, write=SetLeftIndent, nodefault};

Description

Use LeftIndent to indent a paragraph from the left margin of the entire body of text. LeftIndent is useful for making individual paragraphs stand out from the rest of the text.

Note:	Adding bullets to a set of paragraphs by using the Numbering property also affects the left indentation.


TParaAttributes::Numbering

TParaAttributes	See also 	Example

Specifies whether the paragraph is one of a set of bulleted paragraphs.

enum TNumberingStyle { nsNone, nsBullet };

__property TNumberingStyle Numbering = {read=GetNumbering, write=SetNumbering, nodefault};

Description

To insert a bullet to the left of the paragraph, and indent the paragraph sufficiently to accommodate the bullet, set Numbering to nsBullet. If the LeftIndent property is set, bullets will appear at the indentation indicated by LeftIndent, and the body of the paragraph will be further indented to accommodate the bullets.

These are the possible values:

Value	Meaning

nsNone	No numbering on the left.

nsBullet	Bullets on the left with sufficient indentation for the bullets.


TParaAttributes::RightIndent

TParaAttributes	See also

Specifies the indent, in pixels, of the paragraph relative to the right margin.

__property int RightIndent = {read=GetRightIndent, write=SetRightIndent, nodefault};

Description

Use RightIndent to indent a paragraph from the right margin of the entire body of text. RightIndent is useful for making individual paragraphs stand out from the rest of the text, especially when Alignment is set to taRightJustify.


TParaAttributes.Tab

TParaAttributes	See also

Specifies the position, in pixels, of a particular tab stop.

__property int Tab[Byte Index] = {read=GetTab, write=SetTab};

Description

Tab is an indexed property into an array of absolute tab stop positions. The position of the first tab stop is Tab[0], the next tab stop is Tab[1], and so on to Tab[TabCount - 1].

When setting Tab, values of Index below TabCount change the positions of existing tab stops. Values of Index greater than or equal to TabCount increase the number of tab stops in the paragraph and change the value of TabCount.

Note:	Setting Tab does not insert a tab into the text of the paragraph. It sets the positions within the paragraph where tabs will occur if they are inserted. The actual tab characters are inserted into the paragraph by using the Tab key.


TParaAttributes::TabCount

TParaAttributes	See also

Indicates the number of tab stops that are defined for the paragraph.

__property int TabCount = {read=GetTabCount, write=SetTabCount, nodefault};

Description

Read TabCount to determine the number of tab stops in the Tab array. Use TabCount with the Tab property to iterate over all the tab stops defined for the paragraph.


TParaAttributes methods

TParaAttributes	Alphabetically

In TParaAttributes

~TParaAttributes

Assign

TParaAttributes

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TParaAttributes methods

TParaAttributes	By object

~TParaAttributes

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TParaAttributes


TParaAttributes::Assign

TParaAttributes	See also

Copies the properties specified in another TParaAttributes object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to set the paragraph attributes of the selected paragraph from one rich edit control to match the attributes of the selected paragraph of another rich edit control. Since the properties of a TParaAttributes object are only valid when the TParaAttributes exists within a rich edit control, Assign is only useful for copying attributes between rich edit controls.

Note:	Assign only succeeds at runtime when the Source is a TParaAttributes object or an object that has an AssignTo method that is enabled for a TParaAttributes object. Other source objects will throw an EConvertError exception.


TParaAttributes::TParaAttributes

TParaAttributes	See also

Creates an instance of TParaAttributes.

__fastcall TParaAttributes(TCustomRichEdit* AOwner);

Description

Do not call the constructor for a TParaAttributes object, as the properties of a TParaAttributes object are not valid outside of a TCustomRichEdit object. TParaAttributes objects are created from the constructor of a rich edit control that uses them.


TParaAttributes::~TParaAttributes

TParaAttributes

~TParaAttributes frees the memory associated with the TParaAttributes object.

__fastcall virtual ~TParaAttributes(void) { }

Description

Do not call the destructor for a TParaAttributes object, as the properties of a TParaAttributes object are not valid outside of a TCustomRichEdit object. TParaAttributes objects are deleted from the destructor of a rich edit control that uses them.


Hierarchy

TObject

TPersistent


TParam

Hierarchy	Properties	Methods	See also

TParam represents a field parameter.

Unit

dbtables

Description

Use the properties of a TParam to set the value of a parameter that represents the value of a field. Objects that use parameters for the values of fields create TParam objects to represent those parameters. For example, TParams are used by TQuery objects and TStoredProc objects.

TParam shares many properties with TField, as both describe the value of a field in a dataset. However, a TField object has several properties to describe the field binding, and how the field is displayed, edited, or calculated that are not needed in a TParam object. Conversely, TParam includes properties that indicate how the field value is passed as a parameter.


TParam properties

TParam	Alphabetically	Legend

In TParam

AsBCD

AsBlob

AsBoolean

AsCurrency

AsDate

AsDateTime

AsFloat

AsInteger

AsMemo

AsSmallInt

AsString

AsTime

AsWord

Bound

DataType

IsNull

Name

ParamType

Text

Value


TParam properties

TParam	By object	Legend

AsBCD

AsBlob

AsBoolean

AsCurrency

AsDateTime

AsDate

AsFloat

AsInteger

AsMemo

AsSmallInt

AsString

AsTime

AsWord

Bound

DataType

IsNull

Name

ParamType

Text

Value


TParam::AsBCD

TParam	See also 	Example

Specifies the value of the parameter when it represents a binary-coded decimal (BCD) field.

__property System::Currency AsBCD = {read=GetAsBCD, write=SetAsBCD};

Description

Set AsBCD to assign the value for a BCD field to the parameter. AsBCD does not actually take a BCD value. As BCD field objects use the Currency type to represent the value of BCD fields, AsBCD takes a Currency value. Setting AsBCD will set the DataType property to ftBCD.

Read the AsBCD property to determine the value that was assigned to an output parameter, represented as a Currency type. The value of the parameter will be converted to a Currency value if possible.


TParam::AsBlob

TParam	See also

Specifies the value of the parameter when it represents a binary large object (BLOB) field.

__property System::AnsiString AsBlob = {read=GetAsString, write=SetAsBlob};

Description

Set AsBlob to assign the value for a Blob field to the parameter. AsBlob takes a TBlobData value, which is an untyped string of bytes. Setting AsBlob will set the DataType property to ftBlob.

Note:	Applications seldom need to read AsBlob because Blob fields can not be used as output parameters.


TParam::AsBoolean

TParam	See also 	Example

Specifies the value of the parameter when it represents a boolean field.

__property bool AsBoolean = {read=GetAsBoolean, write=SetAsBoolean, nodefault};

Description

Set AsBoolean to assign the value for a boolean field to the parameter. Setting AsBoolean will set the DataType property to ftBoolean.

Read the AsBoolean property to determine the value that was assigned to an output parameter, represented as a Boolean. The value of the parameter will be converted to a Boolean value if possible.


TParam::AsCurrency

TParam	See also 	Example

Specifies the value of the parameter when it represents a currency field.

__property double AsCurrency = {read=GetAsFloat, write=SetAsCurrency};

Description

Set AsCurrency to assign the value for a currency field to the parameter. Setting AsCurrency will set the DataType property to ftCurrency.

Read the AsCurrency property to determine the value that was assigned to an output parameter, represented as a Double. The value of the parameter will be converted to a Double value if possible.

Note:	Do not confuse the AsCurrency property with the Currency data type. Currency fields in database tables store their values as Doubles. The AsBCD property represents the value of the parameter in the Currency data type.


TParam::AsDate

TParam	See also 	Example

Specifies the value of the parameter when it represents a date field.

__property System::TDateTime AsDate = {read=GetAsDateTime, write=SetAsDate};

Description

Set AsDate to assign the value for a date field to the parameter. Setting AsDate will set the DataType property to ftDate.

Read the AsDate property to determine the value that was assigned to an output parameter, represented as a TDateTime. The value of the parameter will be converted to a DateTime value if possible. If the DataType for the parameter is ftDate, only the date portion of the TDateTime value is valid.

The TDateTime type is a Double used by date field objects to hold their values. It actually represents more information than is needed for a date field, which only requires the date portion of the TDateTime value.

The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is fraction of a 24-hour day that has elapsed.


TParam::AsDateTime

TParam	See also 	Example

Specifies the value of the parameter when it represents a date-time field.

__property System::TDateTime AsDateTime = {read=GetAsDateTime, write=SetAsDateTime};

Description

Set AsDate to assign the value for a date-time field to the parameter. Setting AsDateTime will set the DataType property to ftDateTime.

Read the AsDateTime property to determine the value that was assigned to an output parameter, represented as a DateTime. The value of the parameter will be converted to a DateTime value if possible.

The TDateTime type is a Double used by date-time field objects to hold their values. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is fraction of a 24-hour day that has elapsed.


TParam::AsFloat

TParam	See also 	Example

Specifies the value of the parameter when it represents a float field.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

Set AsFloat to assign the value for a float field to the parameter. Setting AsFloat will set the DataType property to ftFloat.

Read the AsFloat property to determine the value that was assigned to an output parameter, represented as a Double. The value of the parameter will be converted to a Double value if possible.


TParam::AsInteger

TParam	See also 	Example

Specifies the value of the parameter when it represents an integer field.

__property int AsInteger = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

Set AsInteger to assign the value for an integer field to the parameter. Setting AsInteger will set the DataType property to ftInteger.

Read the AsInteger property to determine the value that was assigned to an output parameter, represented as a 32-bit integer. The value of the parameter will be converted to a LongInt value if possible.


TParam::AsMemo

TParam	See also

Specifies the value of the parameter when it represents a memo field.

__property System::AnsiString AsMemo = {read=GetAsMemo, write=SetAsMemo};

Description

Set AsMemo to assign the value for a memo field to the parameter. Setting AsMemo will set the DataType property to ftMemo. It is seldom necessary to read AsMemo, because memo fields can not be used as output parameters.

Note:	Some servers support string field types that are too long to fit in the record buffer. These fields are represented as memo fields, although they are not actually Blob fields. When working with such “pseudo-Blob” fields, use the AsString property instead.


TParam::AsSmallInt

TParam	See also 	Example

Specifies the value of the parameter when it represents a small integer field.

__property int AsSmallInt = {read=GetAsInteger, write=SetAsSmallInt, nodefault};

Description

Set AsSmallInt to assign the value for a small integer field to the parameter. Setting AsSmallInt will set the DataType property to ftSmallint.

Read the AsSmallInt property to determine the value that was assigned to an output parameter, represented as a 32-bit integer. The value of the parameter will be converted to a LongInt value if possible.

Note:	AsSmallInt works with a 32-bit integer. Small integer field objects store and manipulate their data as 32-bit integers even though the values in the underlying database are 16-bit integers.


TParam::AsString

TParam	See also 	Example

Specifies the value of the parameter when it represents a string field.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

Set AsString to assign the value for a string field to the parameter. Setting AsString will set the DataType property to ftString.

Read the AsString property to determine the value that was assigned to an output parameter, represented as a string. The value of the parameter will be converted to a string.

Note:	Some servers support string field types that are too long to fit in the record buffer. These fields are represented as memo fields, although they are not actually Blob fields. When working with such “pseudo-Blob” fields, use the AsString property rather than the AsMemo property.


TParam::AsTime

TParam	See also 	Example

Specifies the value of the parameter when it represents a time field.

__property System::TDateTime AsTime = {read=GetAsDateTime, write=SetAsTime};

Description

Set AsTime to assign the value for a time field to the parameter. Setting AsTime will set the DataType property to ftTime.

Read the AsTime property to determine the value that was assigned to the parameter, represented as a DateTime. The value of the parameter will be converted to a DateTime value if possible. If the DataType for the parameter is ftTime, only the time portion of the TDateTime value is valid

The TDateTime type is a Double used by time field objects to hold their values. It actually represents more information than is needed for a time field, which only requires the time portion of the TDateTime value.

The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is fraction of a 24-hour day that has elapsed.


TParam::AsWord

TParam	See also 	Example

Specifies the value of the parameter when it represents a word field.

__property int AsWord = {read=GetAsInteger, write=SetAsWord, nodefault};

Description

Set AsWord to assign the value for a word field to the parameter. Setting AsWord will set the DataType property to ftWord.

Read the AsWord property to determine the value that was assigned to the parameter, represented as a 32-bit integer. The value of the parameter will be converted to a LongInt value if possible.

Note:	AsWord works with a 32-bit integer. Word field objects store and manipulate their data as 32-bit integers even though the values in the underlying database are unsigned 16-bit values.


TParam::Bound

TParam	See also

Indicates whether a value (NULL or otherwise) has been assigned to the parameter.

__property bool Bound = {read=FBound, write=FBound, nodefault};

Description

Read Bound to determine whether a value has been assigned to the parameter. Whenever a value is assigned to the TParam object, Bound is automatically set to true. Set Bound to false to undo the setting of a value. The Clear method will replace the value of the parameter with NULL, but will not set Bound to false. If the Clear method is used to bind the parameter to a NULL value, Bound must be separately set to true.

TQuery objects and TStoredProc objects use the value of Bound to determine whether or not to assign a default value for the parameter. If Bound is false, A TQuery object attempts to assign a value from the dataset indicated by the DataSource property of the query. Similarly, when Bound is false, a TStoredProc object attempts to supply a value directly from the server.


TParam::DataType

TParam 	Example

Indicates the type of field whose value the parameter represents.

__property Db::TFieldType DataType = {read=FDataType, write=SetDataType, nodefault};

Description

DataType is set automatically when a value is assigned to the parameter. Do not set DataType for bound fields, as that may cause the assigned value to be misinterpreted.

Read DataType to discover the type of data that was assigned to the parameter. Each possible value of DataType corresponds to a type of database field.


TParam::IsNull

TParam	See also 	Example

Indicates whether the value assigned to the parameter is NULL (blank).

__property bool IsNull = {read=FNull, nodefault};

Description

Read IsNull to discover if the value of the parameter is NULL, indicating the value of a blank field. NULL values can arise in the following ways:

•	Assigning the value of another, NULL, parameter.

•	Assigning the value of a blank field.

•	Calling the Clear method.

Note:	NULL parameters are not the same as unbound parameters. Unbound parameters have not had a value assigned. NULL parameters have a NULL value. NULL parameters may be bound or unbound.


TParam::Name

TParam	See also

Specifies the name of the parameter.

__property System::AnsiString Name = {read=FName, write=FName};

Description

Use Name to identify a particular parameter within a TParams object. Name is the name of the parameter, not the name of the field whose value the parameter may represent.


TParam::ParamType

TParam 	Example

Indicates the type of the parameter the TParam represents.

__property TParamType ParamType = {read=FParamType, write=FParamType, nodefault};

Description

Objects that use TParam objects to represent field parameters set ParamType to indicate the type of use for the parameter. ParamType must be one of the following values:

Value	Description

ptUnknown	Unknown or undetermined. Before executing a stored procedure, the application must set parameters of this type to another kind.

ptInput	Used to input a field value. Identifies a parameter used to pass values to a stored procedure for processing.

ptOutput	Used to output a field value. Identifies a parameter used by a stored procedure to return values to an application.

ptInputOutput	Used for both input and output.

ptResult	Used as a return value. Identifies a parameter used by a stored procedure to return an error or status value. A stored procedure can only have one parameter of type ptResult.


TParam::Text

TParam	See also

Represents the value of the parameter as a string.

__property System::AnsiString Text = {read=GetAsString, write=SetText};

Description

Set the Text property to assign the value of the parameter to a string without changing the DataType. Unlike the AsString property, which sets the value to a string and changes the DataType, setting the text property converts the string to the DataType of the parameter, and sets the value accordingly. Thus, use AsString to treat the parameter as representing the value of a string field. Use Text instead when assigning a value that is in string form, when making no assumptions about the field type. For example, Text is useful for assigning user data that was input using an edit control.

Reading the Text property is the same as reading the AsString property.


TParam::Value

TParam	See also

Represents the value of the parameter as a Variant.

__property System::Variant Value = {read=GetAsVariant, write=SetAsVariant};

Description

Use Value in generic code that manipulates the values of parameters without needing to know the field type the parameters represent.


TParam methods

TParam	Alphabetically

In TParam

~TParam

Assign

AssignField

AssignFieldValue

Clear

GetData

GetDataSize

LoadFromFile

LoadFromStream

SetBlobData

SetData

TParam

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TParam methods

TParam	By object

~TParam

Assign

AssignField

AssignFieldValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetData

GetDataSize

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

SafeCallException

SetBlobData

SetData

TParam


TParam::Assign

TParam	See also

Copies the Name and Value of another TParam object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to copy from another parameter or from a field component. If the Source parameter is another parameter, Assign transfers the value of

•	The DataType property

•	The Bound property

•	The Value property

•	The Name property

•	The ParamType property only if it is currently ftUnknown.

If the Source parameter is a field component, Assign transfers the value of

•	The DataType property

•	The Value property

•	The Name property (from the FieldName of the field)

When assigning values from a field, Assign sets the Bound property to true.

Note:	Assign does not alter the use of a parameter, only the identifier and the value.


TParam::AssignField

TParam	See also

Assigns the DataType, Name, and Value properties from a TField object.

void __fastcall AssignField(Db::TField* Field);

Description

Use AssignField to set a parameter to represent a particular TField object. AssignField sets the Bound property to true.

Unlike AssignFieldValue, AssignField names the parameter after the field object as well as taking its value.


TParam::AssignFieldValue

TParam	See also

Assigns the DataType and Value properties from a TField object.

void __fastcall AssignFieldValue(Db::TField* Field, const System::Variant &Value);

Description

Use AssignFieldValue to set the Value property to the value passed as the Value parameter. AssignFieldValue assumes that the Value represents a value from a field like the Field parameter, and assigns the DataType property accordingly. AssignFieldValue sets the Bound property to true.

Unlike AssignField, AssignFieldValue does not name the parameter after the field object.


TParam::Clear

TParam	See also

Sets the Value of the parameter to NULL.

void __fastcall Clear(void);

Description

Use Clear to assign a NULL value to a parameter. Calling Clear neither sets nor clears the Bound property. When assigning a NULL value to a parameter, set the Bound property as well as calling Clear.


TParam::TParam

TParam	See also

Creates an instance of TParam and inserts it in a parameter list.

__fastcall TParam(TParams* AParamList, TParamType AParamType);

Description

Call TParam to instantiate a TParam object. TParam objects are usually created by the object that uses them to represent its field parameters, such as a TQuery object or a TStoredProc object.

After allocating the memory for an instance of TParam, TParam

•	Adds the new TParam object to AParamList.

•	Sets the ParamType to AParamType.

•	Initializes the DataType to ftUnknown.

•	Sets the Bound property to false.


TParam::~TParam

TParam	See also

Destroys an instance of TParam.

__fastcall virtual ~TParam(void);

Description

Do not call ~TParam directly in an application. Instead, call Free. Free verifies that the TParam object is not already freed and only then calls ~TParam.

Before freeing the memory associated with the instance of TParam, ~TParam removes the TParam from the parameter list in which it is contained.


TParam::GetData

TParam	See also 	Example

Fills the buffer with the Value of the parameter in the native format of a database field of the appropriate type.

void __fastcall GetData(void * Buffer);

Description

Use GetData to obtain the value of a parameter in the format ready to be written directly to a record buffer. That format is the format used by physical database fields corresponding to DataType. Buffer must have enough space to hold the information. Use the GetDataSize method to determine the necessary size.

The native format for a database field may not be the same as the datatype used by the corresponding field object. Use the As... properties to get the value in the type used by the corresponding field object. Use GetData to get the value in the native database format.

For example, when DataType is ftBCD, GetData retrieves the value in binary-coded decimal, even though the TBCDField object uses Currency to store and manipulate its values. AsBCD gets the value in the Currency type.


TParam::GetDataSize

TParam	See also 	Example

Returns the number of bytes needed to hold the parameter’s value in the format used by the corresponding type of database field.

int __fastcall GetDataSize(void);

Description

Call GetDataSize to determine the number of bytes used to represent the parameter’s value. GetDataSize indicates the buffer size needed before calling the GetData method. The value returned by GetDataSize depends on the Value of the parameter. For some values of DataType, this is always the same:

DataType	Value of DataSize

ftBoolean	2

ftSmallInt	2

ftWord	2

ftAutoInc	4

ftDate	4

ftInteger	4

ftTime	4

ftCurrency	8

ftDateTime	8

ftFloat	8

ftBCD	34

ftString	length of the string + 1

ftVarBytes	throws an EDatabaseError exception

ftBytes	throws an EDatabaseError exception

ftBlob	number of bytes of blob data

ftDBaseOle	number of bytes of blob data

ftFmtMemo	number of bytes of blob data

ftGraphic	number of bytes of blob data

ftMemo	length of memo string + 1

ftParadoxOle	number of bytes of blob data

ftTypedBinary	throws an EDatabaseError exception

ftUnknown	throws an EDatabaseError exception

ftCursor	0

Note:	The size returned by GetDataSize is the size required for the physical database representation of the Value. The field object that corresponds to that physical database field may store its data in another format requiring a different number of bytes.


TParam::LoadFromFile

TParam	See also

Loads the value of a BLOB parameter from the specified file.

void __fastcall LoadFromFile(const System::AnsiString FileName, Db::TBlobType BlobType);

Description

Use LoadFromFile to set the value of a BLOB parameter from a value stored in the file specified by the FileName parameter. The DataType property is set to the value passed as the BlobType parameter.


TParam::LoadFromStream

TParam	See also

Loads the value of a BLOB parameter from a stream.

void __fastcall LoadFromStream(Classes::TStream* Stream, Db::TBlobType BlobType);

Description

Use LoadFromStream to set the value of a BLOB parameter from a value read from the stream specified by the Stream parameter. For example, use LoadFromStream to set the value of a BLOB parameter directly from a TBlobStream object. The DataType property is set to the value passed as the BlobType parameter.


TParam::SetBlobData

TParam	See also

Copies a new value for the parameter in physical database format from Buffer.

void __fastcall SetBlobData(void * Buffer, int Size);

Description

Use SetBlobData to set the value of a parameter from a buffer that contains data from a Binary Large Object (BLOB) field. SetBlobData copies the number of bytes specified by the Size parameter from the buffer specified by the Buffer parameter, and sets the DataType property to ftBlob.


TParam::SetData

TParam	See also 	Example

Copies a new value for the parameter in physical database format from Buffer.

void __fastcall SetData(void * Buffer);

Description

Use SetData to set the value of a parameter from a buffer that contains data in the physical database format. The GetData method of a TField object fetches data in the physical database format. Borland Database Engine API calls can also provide data in physical database format.

Note:	When the DataType property is ftUnknown, ftBytes, ftVarBytes, ftAutoInc, ftBlob, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, or ftTypedBinary, SetData throws an EDatabaseError exception. For BLOB fields, use the SetBlobData method instead.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TParams

Hierarchy	Properties	Methods	See also

TParams manages a list of field parameters.

Unit

dbtables

Description

Use TParams to manage a list of TParam objects for an object that uses field parameters. For example, TStoredProc objects and TQuery objects use TParams objects to create and access their parameters.

Use the properties and methods of TParams to

Access a specific field parameter.

Add or delete field parameters from the list.

Get or set the values of individual field parameters.

Compare field parameters.

Iterate through all field parameters.

Copy a set of field parameters to another parameter list.


TParams properties

TParams	Alphabetically	Legend

In TParams

Items

ParamValues


TParams properties

TParams	By object	Legend

Items

ParamValues


TParams::Items

TParams	See also 	Example

Lists the individual field parameters of a TParams object.

__property TParam* Items[Word Index] = {read=GetParam};

Description

Use Items to iterate through all the field parameters. Index identifies the index in the range 0 to Count - 1. Items can reference a particular parameter by its index, but the ParamByName method is preferred, so as to avoid depending on the order of the parameters.


TParams::ParamValues

TParams	See also

Lists the values of individual field parameters that are specified by name.

__property System::Variant ParamValues[System::AnsiString ParamName] = {read=GetParamValue, write=SetParamValue};

Description

Use ParamValues to get or set the values of individual field parameters that are identified by name. ParamName is a string containing the names of the individual field parameters of interest. If ParamValues is used to access more than one field parameter, the names are separated by semicolons.

Setting ParamValues sets the Value property for each parameter listed in the ParamName string. Specify the values as Variants, in order, in a variant array.

Getting ParamValues retrieves a variant array of variants, each of which represents the value of one of the named parameters.

If ParamName includes a name that does not match any of the field parameters in Items, an exception is thrown.


TParams methods

TParams	Alphabetically

In TParams

~TParams

AddParam

Assign

AssignValues

Clear

Count

CreateParam

GetParamList

IsEqual

ParamByName

RemoveParam

TParams

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TParams methods

TParams	By object

~TParams

AddParam

Assign

AssignValues

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

Count

CreateParam

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParamList

InheritsFrom

InitInstance

InstanceSize

IsEqual

MethodAddress

MethodName

NewInstance

ParamByName

RemoveParam

SafeCallException

TParams


TParams::AddParam

TParams	See also 	Example

Inserts a new field parameter into the Items list.

void __fastcall AddParam(TParam* Value);

Description

Use AddParam to add an instantiated parameter to the Items list. To create a field parameter as well as add it to the list, use CreateParam instead.


TParams::Assign

TParams	See also 	Example

Copies a parameter list from another object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to save and restore a set of parameters or to copy another object's information. Specify the object from which the parameters are to be copied as the value of Source. If Source is another TParams object, Assign discards any current parameter information and replaces it with a copy of the list of field parameters in Source.

Unlike AssignValues, which merely copies the values of the field parameters in the source object’s list, Assign copies the actual field parameters themselves.


TParams::AssignValues

TParams	See also 	Example

Assigns new values to the parameters of the Items property.

void __fastcall AssignValues(TParams* Value);

Description

Use AssignValues to update the values of the field parameters in the Items list to match the values of the corresponding field parameters in another TParams object. For each entry in Items, the AssignValues method attempts to find a parameter with the same Name property in Value. If successful, the parameter information (type and current data) from the Value parameter is assigned to the Items entry. Entries in Items for which no match is found are left unchanged.


TParams::Clear

TParams	See also

Deletes all parameter information from the Items property of the TParams object.

void __fastcall Clear(void);

Description

Use Clear to empty the Items list. Call Clear before building a parameter list to ensure that the list contains only the desired field parameter objects.


TParams::Count

TParams	See also 	Example

Returns the number of entries in the Items property of the TParams object.

int __fastcall Count(void);

Description

Use Count to obtain the number of parameter objects managed by this TParams object. Count can be used when iterating through all the field parameters in the Items list.


TParams::TParams

TParams	See also 	Example

Creates an instance of TParams.

__fastcall virtual TParams(void);

Description

Call TParams to instantiate a TParams object. Most applications will not need to create a TParams list, as it is created by the TQuery or TStoredProc object that uses the TParams object.


TParams::TParams
TParams::CreateParam

TParams	See also 	Example

Creates a new field parameter object and inserts it into the Items list.

TParam* __fastcall CreateParam(Db::TFieldType FldType, const System::AnsiString ParamName, TParamType ParamType);

Description

Call CreateParam to instantiate a new TParam object and add it to the Items managed by this TParams object. Specify the field type of the new parameter as the value of FldType, specify the name of the parameter as the value of ParamName, and specify the type of parameter as the value of ParamType.


TParams::~TParams

TParams	See also

Destroys an instance of TParams.

__fastcall virtual ~TParams(void);

Description

Do not call ~TParams directly in an application. Instead, use delete.

~TParams frees the Items list before calling the parent object’s destructor.


TParams::GetParamList

TParams	See also

Fills a TList object with the individual TParam objects named by ParamNames.

void __fastcall GetParamList(Classes::TList* List, const System::AnsiString ParamNames);

Description

Use GetParamList to obtain a subset of the field parameters in the Items list that have been identified by name. ParamNames is a string giving the names of all field parameters of interest. Multiple parameter names are separated by semicolons.

GetParamList adds the field parameters to List in the order they appear in ParamNames. If ParamNames includes a name that does not match any of the field parameters in Items, an exception is thrown.


TParams::IsEqual

TParams	See also

Indicates whether two TParams objects have identical Items.

bool __fastcall IsEqual(TParams* Value);

Description

IsEqual returns true if the Items property of the Value parameter exactly matches the Items property. To match, each Items list must have the same number of field parameters, in the same order, which match on name, datatype, parameter type, and value.


TParams::ParamByName

TParams	See also 	Example

Locates the parameter with a given name.

TParam* __fastcall ParamByName(const System::AnsiString Value);

Description

Use ParamByName method to find a parameter with the name passed in Value. If a match is found, ParamByName returns the parameter. Otherwise, an exception is thrown. Use this method rather than a direct reference to the Items property to avoid depending on the order of the entries.

To locate more than one parameter at a time, by name, use the GetParamList method instead. To get only the value of a named parameter, use the ParamValues property.


TParams::RemoveParam

TParams	See also 	Example

Removes the specified parameter from the Items property of a TParams object.

void __fastcall RemoveParam(TParam* Value);

Description

Use RemoveParam to remove a field parameter from the Items list. RemoveParam will take Value out of the list but does not free it.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TPasswordDialog

Hierarchy	Properties	Methods	Events	See also

TPasswordDialog is a dialog box that allows the user to specify passwords for the current session.

Unit

dbpwdlg

Description

Use TPasswordDialog to allow the user to specify passwords for the current session. (The current session is represented by a TSession object.) The passwords are used when the application opens a Paradox table that requires a password. If a table requires a password that has not been added to the current session, the user will be prompted for the password.

A TPasswordDialog object is usually created with the PasswordDialog function. However, TPasswordDialog can also be used as a base object for other types of password dialog boxes.


TPasswordDialog properties

TPasswordDialog	Alphabetically	Legend

Derived from TCustomForm

Active

ActiveControl

ActiveMDIChild

ActiveOleControl

BorderIcons

BorderStyle

Canvas

ClientHandle

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

FormStyle

Icon

KeyPreview

MDIChildCount

MDIChildren

Menu

ModalResult

ObjectMenuItem

OleFormObject

Parent

PixelsPerInch

Position

PrintScale

Scaled

TileMode

Visible

WindowMenu

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TPasswordDialog properties

TPasswordDialog	By object	Legend

ActiveControl

ActiveMDIChild

ActiveOleControl

Active

Align

AutoScroll

BorderIcons

BorderStyle

BoundsRect

Brush

Canvas

Caption

ClientHandle

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ControlCount

ControlState

Controls

ControlStyle

Ctl3D

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

FormStyle

Handle

Height

HelpContext

Hint

HorzScrollBar

Icon

KeyPreview

Left

MDIChildCount

MDIChildren

Menu

ModalResult

Name

ObjectMenuItem

OleFormObject

Owner

ParentFont

Parent

ParentWindow

PixelsPerInch

PopupMenu

Position

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

TileMode

Top

VCLComObject

VertScrollBar

Visible

Width

WindowMenu

WindowProc

WindowState


TPasswordDialog events

TPasswordDialog	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnClose

OnCloseQuery

OnCreate

OnDeactivate

OnDestroy

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TPasswordDialog events

TPasswordDialog	By object	Legend

OnActivate

OnClick

OnCloseQuery

OnClose

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TPasswordDialog methods

TPasswordDialog	Alphabetically

In TPasswordDialog

~TPasswordDialog

AddButtonClick

EditChange

OKButtonClick

RemoveAllButtonClick

RemoveButtonClick

TPasswordDialog

Derived from TForm

ArrangeIcons

Cascade

Next

Previous

Tile

Derived from TCustomForm

Close

CloseQuery

DefocusControl

FocusControl

GetFormImage

Hide

Print

Release

SendCancelMode

SetFocus

SetFocusedControl

Show

ShowModal

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPasswordDialog methods

TPasswordDialog	By object

~TPasswordDialog

AddButtonClick

ArrangeIcons

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

Cascade

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

DefaultHandler

DefocusControl

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EditChange

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Next

OKButtonClick

PaintTo

Perform

Previous

Print

Realign

Refresh

Release

RemoveAllButtonClick

RemoveButtonClick

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetFocus

SetFocusedControl

SetTextBuf

Show

ShowModal

Tile

TPasswordDialog

Update

UpdateControlState


TPasswordDialog::AddButtonClick

TPasswordDialog	See also

AddButtonClick controls what happens when the Add button is clicked.

void __fastcall AddButtonClick(System::TObject* Sender);

Description

AddButtonClick adds the password in the edit box to the current session by calling the TSession::AddPassword method. Then AddButtonClick clears and sets focus to the edit box.

After the AddButtonClick method is called, the OKButton is enabled, regardless of whether the edit box currently contains a password.


TPasswordDialog::EditChange

TPasswordDialog	See also

EditChange controls what happens when the contents of the edit box change.

void __fastcall EditChange(System::TObject* Sender);

Description

EditChange enables or disables the Add, OK, and Remove buttons according to whether the edit box contains a password. If the edit box contains a password, the buttons are enabled. Otherwise the buttons are disabled.

Note

If the AddButtonClick method has been called, then the OK button is enabled, regardless of whether the edit box contains a password.


TPasswordDialog::OKButtonClick

TPasswordDialog	See also

OKButtonClick controls what happens when the OK button is clicked.

void __fastcall OKButtonClick(System::TObject* Sender);

Description

OKButtonClick adds the password in the edit box to the current session by calling the TSession::AddPassword method.


TPasswordDialog::RemoveAllButtonClick

TPasswordDialog	See also

RemoveAllButtonClick removes all passwords from the current session.

void __fastcall RemoveAllButtonClick(System::TObject* Sender);

Description

RemoveAllButtonClick removes all passwords from the current session by calling the TSession::RemoveAllPasswords method. Then RemoveAllButtonClick sets focus to the edit box.


TPasswordDialog::RemoveButtonClick

TPasswordDialog	See also

RemoveButtonClick removes the password in the edit box from the current session.

void __fastcall RemoveButtonClick(System::TObject* Sender);

Description

RemoveButtonClick removes the password in the edit box from the current session by calling the TSession::RemovePassword method. Then RemoveButtonClick clears and sets focus to the edit box.


TPasswordDialog::TPasswordDialog

TPasswordDialog	See also

Creates a new TPasswordDialog object.

__fastcall virtual TPasswordDialog(Classes::TComponent* AOwner) : Forms::TForm(AOwner) { }

__fastcall TPasswordDialog(HWND ParentWindow) : Forms::TForm(ParentWindow) { }

__fastcall virtual TPasswordDialog(Classes::TComponent* AOwner, int dummy) : Forms::TForm(AOwner, dummy) { }

Description

Call TPasswordDialog indirectly, using the new keyword, to create a password box at runtime.

Pass a single Component as a parameter to provide the TPasswordDialog object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TPasswordDialog object in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

The third syntax is for loading forms without the associated .DFM file and is rarely used.


TPasswordDialog::~TPasswordDialog

TPasswordDialog

Frees the memory associated with the TPasswordDialog object.

__fastcall virtual ~TPasswordDialog(void) { }

Description

Do not call ~TPasswordDialog directly. Instead, use the delete keyword on the object, which causes ~TPasswordDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm

TForm


TPasswordDialog example

TPasswordDialog


TPen

Hierarchy	Properties	Methods	Events	See also

TPen is used to draw lines or outline shapes on a canvas.

Unit

graphics

Description

Use TPen to describe the attributes of a Windows pen when drawing an image to a canvas (TCanvas). TPen encapsulates the pen properties that are selected into the device context of the canvas.


TPen properties

TPen	Alphabetically	Legend

In TPen

Color

Handle

Mode

Style

Width

Derived from TGraphicsObject

OwnerCriticalSection


TPen properties

TPen	By object	Legend

Color

Handle

Mode

OwnerCriticalSection

Style

Width


TPen::Color

TPen	See also 	Example

Determines the color used to draw lines on the canvas.

__property TColor Color = {read=GetColor, write=SetColor, default=0};

Description

Set Color to change the color used to draw lines or outline shapes. The way the color is used by the pen depends on the Mode and Style properties.


TPen::Handle

TPen	See also

Specifies the Windows pen object handle.

__property HPEN Handle = {read=GetHandle, write=SetHandle, nodefault};

Description

Use Handle when making a Windows API function call that requires the handle of a pen object. Handle is the Windows handle currently selected into the device context of the canvas.


TPen::Mode

TPen	See also

Determines how the pen draws lines on the canvas.

enum TPenMode { pmBlack, pmWhite, pmNop, pmNot, pmCopy, pmNotCopy, pmMergePenNot, pmMaskPenNot, pmMergeNotPen, pmMaskNotPen, pmMerge, pmNotMerge, pmMask, pmNotMask, pmXor, pmNotXor };

__property TPenMode Mode = {read=FMode, write=SetMode, default=4};

Description

Set Mode to determine how the color of the pen interacts with the color on the canvas. The effects of Mode are described in the following table:

Mode	Pixel color

pmBlack	Always black

pmWhite	Always white

pmNop	Unchanged

pmNot	Inverse of canvas background color

pmCopy	Pen color specified in Color property

pmNotCopy	Inverse of pen color

pmMergePenNot	Combination of pen color and inverse of canvas background

pmMaskPenNot	Combination of colors common to both pen and inverse of canvas background.

pmMergeNotPen	Combination of canvas background color and inverse of pen color

pmMaskNotPen	Combination of colors common to both canvas background and inverse of pen

pmMerge	Combination of pen color and canvas background color

pmNotMerge	Inverse of pmMerge: combination of pen color and canvas background color

pmMask	Combination of colors common to both pen and canvas background

pmNotMask	Inverse of pmMask: combination of colors common to both pen and canvas background

pmXor	Combination of colors in either pen or canvas background, but not both

pmNotXor	Inverse of pmXor: combination of colors in either pen or canvas background, but not both


TPen::Style

TPen	See also 	Example

Determines the style in which the pen draws lines.

enum TPenStyle { psSolid, psDash, psDot, psDashDot, psDashDotDot, psClear, psInsideFrame };

__property TPenStyle Style = {read=GetStyle, write=SetStyle, default=0};

Description

Use Style to draw a dotted or dashed line, or to omit the line that appears as a frame around shapes. These are the possible values of Style:

Style	Meaning

psSolid	A solid line.

psDash	A line made up of a series of dashes

psDot	A line made up of a series of dots

psDashDot	A line made up of alternating dashes and dots

psDashDotDot	A line made up of a serious of dash-dot-dot combinations

psClear	No line is drawn (used to omit the line around shapes that draw an outline using the current pen).

psInsideFrame	A solid line, but one that may use a dithered color if Width is greater than 1.

Note:	Only the psInsideFrame style will produce a dithered color to match a Color property that is not in the color table. All others choose the closest color from the Windows color table.

Note:	Dotted or dashed pen styles are not available when the Width property is not 1.


TPen::Width

TPen	See also 	Example

Specifies the maximum width of the pen in pixels.

__property int Width = {read=GetWidth, write=SetWidth, default=1};

Description

Use Width to give the line greater weight. If Width is set to a value less than 1, the pen is given a Width of 1.

Note:	The value of Width influences which values of Style are valid.


TPen events

TPen	Alphabetically

Derived from TGraphicsObject

OnChange


TPen events

TPen	By object

OnChange


TPen methods

TPen	Alphabetically

In TPen

~TPen

Assign

TPen

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPen methods

TPen	By object

~TPen

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TPen


TPen::Assign

TPen	See also

Assigns the properties of the pen from another TPen object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

If the Source parameter identifies another TPen object, Assign copies the Color, Width, Style, and Mode properties of the source pen. Otherwise, the parent class’s method copies the properties from any object that can write to a TPen object in its AssignTo method.


TPen::TPen

TPen	See also

Creates an instance of TPen.

__fastcall TPen(void);

Description

Do not call TPen directly to create a TPen object for assigning the pen property of a canvas. Instead, use the new keyword. The pen for the canvas is created automatically in the constructor for the TCanvas object.

TPen allocates the resources for the TPen object and initializes the Mode property to pmCopy.


TPen::~TPen

TPen	See also

Destroys an instance of TPen.

__fastcall virtual ~TPen(void);

Description

Do not call ~TPen directly from an application. Instead, use the delete keyword, which takes an indirect reference to a TPen object.


Scope

Published


Hierarchy

TObject

TPersistent

TGraphicsObject


TPersistent

Hierarchy	Methods	See also

TPersistent is the ancestor for all objects that have assignment and streaming (dfm format) capabilities.

Unit

classes

Description

TPersistent encapsulates the behavior common to all objects that can be assigned to other objects, and that can read and write their properties to and from a stream. For this purpose TPersisent introduces methods that can be overriden to:

•	Define the procedure for loading and storing unpublished data to a stream.

•	Provide the means to assign values to properties.

•	Provide the means to assign the contents of one object to another.

Do not create instances of TPersistent. Use TPersistent as a base class when declaring objects that are not components, but that need to be saved to a stream or have their properties assigned to other objects.


TPersistent methods

TPersistent	Alphabetically	Legend

In TPersistent

~TPersistent

Assign

AssignTo

DefineProperties

GetNamePath

GetOwner

TPersistent

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPersistent methods

TPersistent	By object	Legend

~TPersistent

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DefineProperties

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetOwner

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TPersistent


TPersistent::Assign

TPersistent	See also

Copies one object to another by copying the contents of that object to the other.

virtual void __fastcall Assign(TPersistent* Source);

Description

Call Assign to copy the properties or other attributes of one object from another. The standard form of a call to Assign is

Destination->Assign(Source);

which tells the Destination object to copy the contents of the Source object to itself.

If the destination object does not override the Assign method to handle an assignment of properties from Source, TPersistent::Assign calls the source object’s AssignTo method to allow the source object to handle the assignment. If the Source object is NULL, TPersistent::Assign throws an EConvertError.

In general, the statement “Destination = Source” is not the same as the statement “Destination->Assign(Source)”. The statement “Destination = Source” makes Destination reference the same object as Source, whereas "Destination->Assign(Source)" copies the contents of the object referenced by Source into the object referenced by Destination.

Note:	The types of some properties are also objects. If these properties have write methods that use Assign to set the value of the property, then in these cases the statement "Destination = Source" is the same as "Destination->Assign(Source)".


TPersistent::AssignTo

TPersistent	See also

Copies the properties of an object to a destination object.

virtual void __fastcall AssignTo(TPersistent* Dest);

Description

Override the AssignTo method to extend the functionality of the Assign method of destination objects so that they handle newly created object classes. When defining a new object class, override the Assign method for every existing object class that should be able to copy its properties to the new class.  Override the AssignTo method for every existing class that the new class can copy to.

The Assign method of TPersistent calls AssignTo if the descendant object does not succeed in copying the properties of a source object. By default, the AssignTo method defined by TPersistent throws an EConvertError exception.

For example, given the following code in which A and B are instance variables:

A->Assign(B);

if A knows how to handle B, then it does so and returns. If A doesn’t know how to handle B’s type, execution will trickle up to TPersistent::Assign, which will call:

B->AssignTo(A);

If B knows how to copy to A, the assignment will succeed. Otherwise, an exception is thrown.


TPersistent::DefineProperties

TPersistent	See also

Provides an interface for a method that reads and writes otherwise unpublished data.

virtual void __fastcall DefineProperties(TFiler* Filer);

Description

Descendants of TPersistent can override DefineProperties to designate a method for storing the object's unpublished data to a stream such as a form file. By default, writing an object to a stream writes the values of all its published properties, and reading the object in reads those values and assigns them to the properties. Objects can also specify methods that read and write data other than published properties by overriding the DefineProperties method.

When overriding DefineProperties, consider including some or all of the following:

•	A call to the parent class’s method

•	Calls to the filer object's DefineProperty method

•	Calls to the filer object's DefineBinaryProperty method

DefineProperties is virtual, so descendant classes can override it as necessary but are not required to redefine it.


TPersistent::~TPersistent

TPersistent	See also

Destroys the TPersistent instance and frees its memory.

__fastcall virtual ~TPersistent(void);

Description

~TPersistent cleans up references in the global fix-up list for form linking. It then calls the parent object’s destructor method.

Do not call ~TPersistent directly. Instead, use the delete keyword for a descendant of TPersistent.


TPersistent::GetNamePath

TPersistent	See also

Returns the name of the object as it appears in the Object Inspector.

DYNAMIC System::AnsiString __fastcall GetNamePath();

Description

GetNamePath is for internal use only. It is used to determine the text to display in the Object Inspector for the name of the object being edited. GetNamePath is introduced in TPersistent so that descendants like collections can appear in the Object Inspector. Do not call GetNamePath directly.

Note:	For components, this is the component name. For TCollectionItem objects it is the name of the hosting component, the name of the property, and the index into the collection surrounded by brackets.


TPersistent::GetOwner

TPersistent	See also

Returns the owner of an object.

DYNAMIC TPersistent* __fastcall GetOwner(void);

Description

GetOwner is used by the GetNamePath method to find the owner of a component. GetNamePath and GetOwner are introduced in TPersistent so that descendants like collections can appear in the Object Inspector. By default for TPersistent GetOwner returns NULL. For TCollection, it is the owner of the collection. The TCollectionItem::GetOwner returns the collection object the item into which the collection object has been inserted. For TComponent it is the value of the Owner property.


TPersistent::TPersistent

TPersistent

Creates a new TPersistent object.

__fastcall TPersistent(void) : System::TObject() { }

Description

Do not create instances of TPersistent. TPersistent is intended only as a base class for other object classes. When creating descendant classes, use the new keyword.


Scope

Protected


Hierarchy

TObject


TPictureAdapter

Hierarchy	Properties	Methods	See also

TPictureAdapter connects a native TPicture object to an OLE picture object.

Unit

axctrls

Description

To create an instance of a TPictureAdapter, call the GetOlePicture procedure in order to create the binding between a TPicture and an OLE picture object.


TPictureAdapter properties

TPictureAdapter	Alphabetically	Legend

Derived from TInterfacedObject

RefCount


TPictureAdapter properties

TPictureAdapter	By object	Legend

RefCount


TPictureAdapter methods

TPictureAdapter	Alphabetically

In TPictureAdapter

~TPictureAdapter

TPictureAdapter

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPictureAdapter methods

TPictureAdapter	By object

~TPictureAdapter

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TPictureAdapter


TPictureAdapter::TPictureAdapter

TPictureAdapter	See also

Constructs an instance of the picture adapter control.

__fastcall TPictureAdapter(Graphics::TPicture* Picture);

Description

Do not call the constructor for this class directly. Instead, call the GetOlePicture procedure to create the binding between a TPicture and an OLE picture object


TPictureAdapter::~TPictureAdapter

TPictureAdapter

~TPictureAdapter frees the memory associated with the TPictureAdapter object.

__fastcall virtual ~TPictureAdapter(void) { }

Description

Do not call ~TPictureAdapter directly. Instead, use the delete keyword on the object, which causes ~TPictureAdapter to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject

TCustomAdapter


TPicture

Hierarchy	Properties	Methods	Events	See also

TPicture contains a bitmap, icon, metafile graphic, or user-defined graphic.

Unit

graphics

Description

TPicture is a TGraphic container, used to hold a graphic, whose type is specified in the Graphic property. It is used in place of a TGraphic if the graphic can be of any TGraphic class. LoadFromFile and SaveToFile are polymorphic. For example, if the TPicture is holding an Icon, it is valid to LoadFromFile a bitmap file, where if the class was TIcon it would only be valid to read .ICO files.

If the TPicture contains a bitmap graphic, the Bitmap property specifies the graphic. If the TPicture contains an icon graphic, the Icon property specifies the graphic. If the TPicture contains a metafile graphic, the Metafile property specifies the graphic.

The properties of TPicture indicate the type of graphic that the picture object contains, and its size. The methods of TPicture are used to load, save, and manipulate graphics.

To load or save a picture to the Clipboard, use the Assign method of a TClipboard object.

To draw a picture on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing the Graphic property of a TPicture as a parameter.


TPicture properties

TPicture	Alphabetically	Legend

In TPicture

Bitmap

Graphic

Height

Icon

Metafile

PictureAdapter

Width


TPicture properties

TPicture	By object	Legend

Bitmap

Graphic

Height

Icon

Metafile

PictureAdapter

Width


TPicture::Bitmap

TPicture	See also

Specifies the contents of the picture object as a bitmap graphic (.BMP file format).

__property TBitmap* Bitmap = {read=GetBitmap, write=SetBitmap};

Description

Use Bitmap to reference the picture object when it contains a bitmap. If Bitmap is referenced when the picture contains a Metafile or Icon graphic, the graphic won't be converted. Instead, the original contents of the picture are discarded and Bitmap returns a new, blank bitmap.


TPicture::Graphic

TPicture	See also 	Example

Specifies the graphic that the picture contains.

__property TGraphic* Graphic = {read=FGraphic, write=SetGraphic};

Description

Use Graphic to specify what graphic the TPicture object contains. The graphic can be a bitmap, icon, or metafile, or user-defined graphic class.


TPicture::Height

TPicture 	See also

Specifies the vertical size (in pixels) of the graphic.

__property int Height = {read=GetHeight, nodefault};

Description

Use Height to find the height of the graphic image contained in the picture object. Height is the native, unstretched, height of the picture.


TPicture::Icon

TPicture	See also

Specifies the contents of the TPicture object as an icon graphic (.ICO file format).

__property TIcon* Icon = {read=GetIcon, write=SetIcon};

Description

If Icon is referenced when the TPicture contains a Bitmap or Metafile graphic, the graphic won't be converted. Instead, the original contents of the TPicture are discarded and Icon returns a new, blank icon.


TPicture::Metafile

TPicture	See also

Specifies the contents of the picture object as an Enhanced Windows metafile graphic (.EMF file format).

__property TMetafile* Metafile = {read=GetMetafile, write=SetMetafile};

Description

If Metafile is referenced when the TPicture contains a Bitmap or Icon graphic, the graphic won't be converted. Instead, the original contents of the TPicture are discarded and Metafile returns a new, blank metafile.


TPicture::PictureAdapter

TPicture

Represents an OLE interface for the picture.

__property _di_IChangeNotifier PictureAdapter = {read=FNotify, write=FNotify};

Description

PictureAdapter is for internal use only.


TPicture::Width

TPicture	See also

Specifies the horizontal size (in pixels) of the picture.

__property int Width = {read=GetWidth, nodefault};

Description

Use Width to find the width of a graphic image. Width contains the native, unstretched, width of the picture.


TPicture events

TPicture	Alphabetically

In TPicture

OnChange

OnProgress


TPicture events

TPicture	By object

OnChange

OnProgress


TPicture::OnChange

TPicture

Occurs when the specific graphics item encapsulated by the picture object changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Use OnChange to write an event handler to process an action when the graphic is modified.


TPicture::OnProgress

TPicture	See also

Occurs periodically during slow operations that affect the graphic.

__property TProgressEvent OnProgress = {read=FOnProgress, write=FOnProgress};

Description

OnProgress is generated by the particular graphic that the picture object contains. Whether OnProgress occurs depends upon the type of graphic in the Graphic property. Some graphics generate this event, others do not. JPeg images, for example, generate an OnProgress event.

Write an OnProgress event handler to provide the user with feedback during slow operations such as loading large compressed images. TImage, for example, hooks the OnProgress event of TPicture.

The Stage parameter indicates whether the operation is beginning, continuing, or ending. If the OnProgress event handler displays an indicator such as a progress bar, the indicator can be created when Stage is psStarting, updated while Stage is psRunning, and removed when Stage is psEnding. The PercentDone parameter is an approximation of how much of the operation has completed. Use PercentDone to update the position of a progress bar or other indicator.

The RedrawNow parameter indicates whether the image can safely be drawn on screen at this point. The R parameter specifies the portion of the image that has changed and needs to be redrawn.

The Msg parameter contains one or two words that describe what operation is occurring. For example, the value of Msg could be a string such as Loading, Storing, or Reducing colors. The Msg string can also be empty.

Note:	The PercentDone parameter is only an approximation. With some image formats, the value of PercentDone may actually decrease from the value in previous events, as the graphic object discovers there is more work to do.


TPicture methods

TPicture	Alphabetically

In TPicture

~TPicture

Assign

LoadFromClipboardFormat

LoadFromFile

RegisterClipboardFormat

RegisterFileFormat

RegisterFileFormatRes

SaveToClipboardFormat

SaveToFile

SupportsClipboardFormat

TPicture

UnregisterGraphicClass

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPicture methods

TPicture	By object

~TPicture

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

LoadFromClipboardFormat

LoadFromFile

MethodAddress

MethodName

NewInstance

RegisterClipboardFormat

RegisterFileFormat

RegisterFileFormatRes

SafeCallException

SaveToClipboardFormat

SaveToFile

SupportsClipboardFormat

TPicture

UnregisterGraphicClass


TPicture::Assign

TPicture	See also 	Example

Copies one object to another by copying the contents of that object to the other.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

When Source is a object type that is valid for the Graphic property, Assign makes that graphic the value of the Graphic property.

The actions performed by Assign depend on the actual types of the TPicture Graphic property and Source. For example, if the Graphic property and Source are bitmaps (TBitmap), the bitmap contained in Source is copied into the Graphic property. Similar conversions are valid, for example, for TIcon or TMetafile.

If the Source parameter is not a valid object for the Graphic property, Assign calls the parent class's method so that the picture can be copied from any object with which it is compatible.


TPicture::TPicture

TPicture	See also

Creates a TPicture object.

__fastcall TPicture(void);

Description

Call TPicture indirectly, using the new keyword, to create an instance of TPicture at runtime. TPicture allocates the memory for the picture object and initializes its internal formats. After creating the TPicture object, use the LoadFromClipboardFormat or LoadFromFile method to assign a graphical image to the picture, so that it is available to the application.


TPicture::~TPicture

TPicture	See also

Destroys an instance of a picture object.

__fastcall virtual ~TPicture(void);

Description

Do not call ~TPicture directly in an application. Instead, use the delete keyword.

~TPicture frees the graphic image it contains before calling the parent object’s destructor.


TPicture::LoadFromClipboardFormat

TPicture	See also

Reads the picture from the handle provided in the given Clipboard format.

void __fastcall LoadFromClipboardFormat(Word AFormat, int AData, HPALETTE APalette);

Description

Use LoadFromClipboardFormat to read in a graphic from the Clipboard. If the format is not supported, an EInvalidGraphic exception is thrown.


TPicture::LoadFromFile

TPicture	See also

Reads the file specified in Filename and loads the data into the TPicture object.

void __fastcall LoadFromFile(const System::AnsiString Filename);

Description

Use LoadFromFile to read a picture from disk. The TGraphic class created determined by the file extension of the file. If the file extension is not recognized an EInvalidGraphic exception is thrown.


TPicture::RegisterClipboardFormat

TPicture	See also

Registers a new TGraphic class for use in the LoadFromClipboardFormat method.

static void __fastcall RegisterClipboardFormat(System::TMetaClass* vmt, Word AFormat, System::TMetaClass* AGraphicClass);

Description

Use RegisterClipboardFormat register a new graphic format with TPicture so that it can be used with the LoadFromClipboardFormat method.


TPicture::RegisterFileFormat

TPicture	See also

Registers a new TGraphic class for use in LoadFromFile.

static void __fastcall RegisterFileFormat(System::TMetaClass* vmt, const System::AnsiString AExtension, const System::AnsiString ADescription, System::TMetaClass* AGraphicClass);

Description

Use RegisterFileFormat to register a graphic file format with TPicture so that it can be used with a Open or Save dialog box.

The AExtension parameter specifies the three-character system file extension to associate with the graphic class (for example, "BMP" is associated with TBitmap). The ADescription parameter specifies the description of the graphic to appear in the drop down list of the dialog box (for example, "Bitmaps" is the description of TBitmap). The AGraphicClass parameter registers the new graphic class to associate with the file format.


TPicture::RegisterFileFormatRes

TPicture	See also

Registers a new TGraphic class for use in the LoadFromFile method.

static void __fastcall RegisterFileFormatRes(System::TMetaClass* vmt, const System::AnsiString AExtension, int ADescriptionResID, System::TMetaClass* AGraphicClass);

Description

Use RegisterFileFormatRes by specifying a string resource ID in the ADescriptionResID parameter.


TPicture::SaveToClipboardFormat

TPicture	See also

Allocates a global handle and writes the picture in its native Clipboard format (CF_BITMAP for bitmaps, CF_METAFILE for metafiles, and so on).

void __fastcall SaveToClipboardFormat(Word &AFormat, int &AData, HPALETTE &APalette);

Description

The Formats property of TClipboard will contain the formats written. SaveToClipboardFormat returns the number of Clipboard items written to the array pointed to by AFormat and AData. If either AFormat or AData are NULL, SaveToClipboardFormat returns the number of Clipboard items that would have been saved.


TPicture::SaveToFile

TPicture

Writes the picture to disk.

void __fastcall SaveToFile(const System::AnsiString Filename);

Description

Use SaveToFile to save a TPicture object to the file specified in Filename.


TPicture::SupportsClipboardFormat

TPicture	See also

Indicates if the given Clipboard format is supported by the LoadFromClipboardFormat method.

static bool __fastcall SupportsClipboardFormat(System::TMetaClass* vmt, Word AFormat);

Description

If the LoadFromClipboardFormat method supports the Clipboard format specified as the value of AFormat, SupportsClipboardFormat returns true. If the format is not supported, the method returns false.


TPicture::UnregisterGraphicClass

TPicture	See also

Removes all references to the specified TGraphic class and all its descendants from the internal lists of file formats and clipboard formats.

static void __fastcall UnregisterGraphicClass(System::TMetaClass* vmt, System::TMetaClass* AClass);

Description

Call UnregisterGraphicClass to make a graphic class unavailable to all picture objects. UnregisterGraphicClass reverses the registration accomplished by the RegisterFileFormat, RegisterFileFormatRes, or RegisterClipboardFormat method.

When a graphic class is registered, the global GraphicFilter, GraphicExtension, and GraphicFileMask functions can return dialog filter strings, default file extensions or file filters for the graphic class. Call UnregisterGraphicClass when these values should not be available. For example, component writers who implement custom graphic classes unregister those classes in the finalization block of the unit that implements the custom class. (File formats and clipboard formats for the custom class are registered in the initialization block).


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TParamList

Hierarchy	Properties	Methods	See also

TParamList manages a list of session parameters.

Unit

dbtables

Description

Do not use TParamList directly. TParamList is an internal object used to manage a list of session parameters for a TSession component.


TParamList properties

TParamList	Alphabetically	Legend

In TParamList

Buffer

FieldCount

FieldDescs


TParamList properties

TParamList	By object	Legend

Buffer

FieldCount

FieldDescs


TParamList::Buffer

TParamList	See also

Contains all parameter strings for the parameter list.

__property char * Buffer = {read=FBuffer};

Description

Buffer is used internally to store parameters in the the parameter list object. While applications can parse this list, there is usually no need to do so.


TParamList::FieldCount

TParamList	See also

Indicates the number of session parameters in the parameter list.

__property int FieldCount = {read=FFieldCount, nodefault};

Description

Check FieldCount to determine how many parameters there are for a session.


TParamList::FieldDescs

TParamList 	See also

Contains the field descriptors for each parameter maintained by the parameter list object.

__property PFieldDescList FieldDescs = {read=FFieldDescs};

Description

Examine FieldDescs to determine the characteristics of each parameter maintained by the parameter list object. Applications usually have no need to access this property directly.


TParamList methods

TParamList	Alphabetically

In TParamList

~TParamList

TParamList

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TParamList methods

TParamList	By object

~TParamList

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TParamList


TParamList::TParamList

TParamList	See also

Creates an instance of TParamList.

__fastcall TParamList(Classes::TStrings* Params);

Description

Call TParamList to instantiate a TParamList object. Most applications do not need to create a TParamList object because it is automatically created by TSession.

Params is a string list containing the names of the parameters to create for the session. These parameters correspond to Borland Database Engine (BDE) configuration parameters.


TParamList::~TParamList

TParamList	See also

Destroys an instance of TParamList.

__fastcall virtual ~TParamList(void);

Description

Do not call ~TParamList directly in an application. Instead, call Free. Free verifies that the TParamList object is not already freed, and only then calls ~TParamList.

~TParamList frees the memory previously allocated for field descriptors and the buffer used by TParamList.

Note:	An application should never need to destroy a TParamList object. It is automatically destroyed when its parent session object is destroyed.


Accessibility

Read-only


Hierarchy

TObject


 TPopupMenu

Hierarchy	Properties	Methods	Events	See also

TPopupMenu encapsulates the properties, methods, and events of a pop-up menu.

Unit

menus

Description

Use TPopupMenu to define the pop-up menu that appears when the user clicks on a control with the right mouse button. To make a pop-up menu available, assign the TPopupMenu object to the control’s PopupMenu property.


TPopupMenu properties

TPopupMenu	Alphabetically	Legend

In TPopupMenu

Alignment

AutoPopup

HelpContext

PopupComponent

Derived from TMenu

Handle

Items

WindowHandle

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TPopupMenu properties

TPopupMenu	By object	Legend

Alignment

AutoPopup

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Handle

HelpContext

Items

Name

Owner

PopupComponent

Tag

VCLComObject

WindowHandle


TPopupMenu::Alignment

TPopupMenu	See also

Determines where the pop-up menu appears when the user clicks the right mouse button.

enum TPopupAlignment { paLeft, paRight, paCenter };

__property TPopupAlignment Alignment = {read=FAlignment, write=FAlignment, default=0};

Description

Set Alignment to control the placement of the popup menu. These are the possible values:

Value	Meaning

paLeft	The pop-up menu appears with its top left corner under the mouse pointer.

paCenter	The pop-up menu appears with the top center of the menu under the mouse pointer.

paRight	The pop-up menu appears with its top right corner under the mouse pointer.

The default value is paLeft.


TPopupMenu::AutoPopup

TPopupMenu	See also 	Example

Determines whether the pop-up menu appears automatically when the user clicks the right mouse button.

__property bool AutoPopup = {read=FAutoPopup, write=FAutoPopup, default=1};

Description

Set AutoPopup to true to cause the pop-up menu to appear automatically when the user clicks the right mouse button on a control that has the pop-up menu specified as its PopupMenu property. The application key present on keyboards specifically designed for Windows 95 will also show this menu when pressed.

Set AutoPopup to false if the appearance of the pop-up menu should be controlled programmatically. To display a pop-up menu when AutoPopup is false, use the Popup method.


TPopupMenu::HelpContext

TPopupMenu	See also

Specifies a context ID for the entire pop-up menu.

typedef int THelpContext;

__property Classes::THelpContext HelpContext = {read=GetHelpContext, write=SetHelpContext, default=0};

Description

Use HelpContext to associate a help screen with the entire pop-up menu. Each screen in the Help system should have a unique context ID. When a component is selected in the application, pressing F1 displays the Help screen associated with the value of HelpContext.

To associate a help screen with the individual items in the pop-up menu, use the HelpContext property of the associated TMenuItem objects.


TPopupMenu::PopupComponent

TPopupMenu	See also 	Example

Indicates the component that last displayed the popup menu in response to a right mouse click.

__property Classes::TComponent* PopupComponent = {read=FPopupComponent, write=FPopupComponent};

Description

Read PopupComponent to determine which control is currently using the popup menu. In applications where multiple controls share the same pop-up menu, use PopupComponent to determine which of them displayed the menu.

Set PopupComponent to associate a control with the menu before calling the Popup method programmatically to bring up the pop-up menu.


TPopupMenu events

TPopupMenu	Alphabetically	Legend

In TPopupMenu

OnPopup


TPopupMenu events

TPopupMenu	By object	Legend

OnPopup


TPopupMenu::OnPopup

TPopupMenu	See also 	Example

Occurs just before the pop-up menu appears.

__property Classes::TNotifyEvent OnPopup = {read=FOnPopup, write=FOnPopup};

Description

Write an OnPopup event handler to take specific action just before the pop-up menu appears. For example, use an OnPopup event handler to set the Checked, Enabled, or Visible property of individual items in the menu so that they are appropriate to the PopupComponent.


TPopupMenu methods

TPopupMenu	Alphabetically

In TPopupMenu

~TPopupMenu

Popup

TPopupMenu

Derived from TMenu

DispatchCommand

DispatchPopup

FindItem

GetHelpContext

IsShortCut

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPopupMenu methods

TPopupMenu	By object

~TPopupMenu

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

DispatchCommand

DispatchPopup

FieldAddress

FindComponent

FindItem

Free

FreeInstance

FreeNotification

FreeOnRelease

GetHelpContext

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsShortCut

MethodAddress

MethodName

NewInstance

Popup

RemoveComponent

SafeCallException

TPopupMenu


TPopupMenu::TPopupMenu

TPopupMenu	See also

Creates an instance of TPopupMenu.

__fastcall virtual TPopupMenu(Classes::TComponent* AOwner);

Description

Call TPopupMenu indirectly, using the new keyword, to create to create a pop-up menu at runtime. Pop-up menus placed in forms or data modules at design time are created automatically.


TPopupMenu::~TPopupMenu

TPopupMenu	See also

Destroys an instance of TPopupMenu.

__fastcall virtual ~TPopupMenu(void);

Description

Do not call ~TPopupMenu directly in an application. Instead, use the delete keyword.


TPopupMenu::Popup

TPopupMenu	See also 	Example

Displays the pop-up menu onscreen.

virtual void __fastcall Popup(int X, int Y);

Description

Call Popup to bring up the pop-up menu. The menu appears at the screen coordinates indicated by the values (in pixels) of X and Y.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TMenu


 TProgressBar

Hierarchy	Properties	Methods	Events

TProgressBar is a wrapper for a Windows progress bar.

Unit

comctrls

Description

Use TProgressBar to add a progress bar to a form. Progress bars provide users with visual feedback about the progress of a procedure within an application. As the procedure progresses, the rectangular progress bar gradually fills from left to right with the system highlight color.


TProgressBar properties

TProgressBar	Alphabetically	Legend

In TProgressBar

Max

Min

Position

Step

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TProgressBar properties

TProgressBar	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Handle

Height

HelpContext

Hint

Left

Max

Min

Name

Owner

Parent

ParentShowHint

ParentWindow

PopupMenu

Position

ShowHint

Showing

Step

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TProgressBar.Max

TProgressBar	See also	Example

Specifies the upper limit of the range of possible positions.

__property int Max = {read=GetMax, write=SetMax, nodefault};

Description

Use Max along with the Min property to establish the range of possible positions a progress bar. When the process tracked by the progress bar is complete, the value of Position should equal Max.


TProgressBar.Min

TProgressBar	See also	Example

Specifies the lower limit of the range of possible positions.

__property int Min = {read=GetMin, write=SetMin, nodefault};

Description

Use Max along with the Min property to establish the range of possible positions a progress bar. When the process tracked by the progress bar begins, the value of Position should equal Min.


TProgressBar::Position

TProgressBar	See also	Example

Specifies the current position of the progress bar.

__property int Position = {read=GetPosition, write=SetPosition, default=0};

Description

Read Position to determine how far the process tracked by the progress bar has advanced from Min toward Max. Set Position to cause the progress bar to display a position between Min and Max. For example, when the process tracked by the progress bar completes, set Position to Max so that it appears completely filled.

When a progress bar is created, Min and Max represent percentages, where Min is 0 (0% complete) and Max is 100 (100% complete). If these values are not changed, Position is the percentage of the process that has already been completed.


TProgressBar::Step

TProgressBar	See also	Example

Specifies the amount that Position increases when the StepIt method is called.

__property int Step = {read=FStep, write=SetStep, default=10};

Description

Set Step to specify the granularity of the progress bar. Step should reflect the size of each step in the process tracked by the progress bar, in the logical units used by the Max and Min properties.

When a progress bar is created, Min and Max represent percentages, where Min is 0 (0% complete) and Max is 100 (100% complete). If these values are not changed, Step is the percentage of the process completed before the user is provided with additional visual feedback.

When the StepIt method is called, the value of Position increases by Step.


TProgressBar events

TProgressBar	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TProgressBar events

TProgressBar	By object	Legend

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TProgressBar methods

TProgressBar	Alphabetically

In TProgressBar

~TProgressBar

StepBy

StepIt

TProgressBar

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TProgressBar methods

TProgressBar	By object

~TProgressBar

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

StepBy

StepIt

TProgressBar

Update

UpdateControlState


TProgressBar::TProgressBar

TProgressBar	See also	Example

Creates an instance of TProgressBar.

__fastcall virtual TProgressBar(Classes::TComponent* AOwner);

__fastcall TProgressBar(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Call TProgressBar indirectly, using the new keyword, to create a progress bar at runtime. Progress bars placed on forms at design time are created automatically.

Pass a single Component as a parameter to provide the progress bar with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the progress bar in a non-VCL window. This syntax is used when the progress bar is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent class’s constructor, TProgressBar initializes the following values:

•	Min is set to 0 and Max to 100.

•	Step is set to 10.

•	Width is set to 150.

•	Height is set to the height the arrow bitmap on a scrollbar.


TProgressBar::StepBy

TProgressBar	See also	Example

Advances the Position of the progress bar by a specified amount.

void __fastcall StepBy(int Delta);

Description

Call StepBy to increase the value of Position by the value of the Delta parameter. To advance Position by a default amount that represents a single step in the process, use the StepIt method.


TProgressBar::StepIt

TProgressBar	See also	Example

Advances Position by the amount specified in the Step property.

void __fastcall StepIt(void);

Description

Call the StepIt method to increase the value of Position by the value of the Step property. If Step represents the size of one logical step in the process tracked by the progress bar, call Step after each logical step is completed.


TProgressBar::~TProgressBar

TProgressBar

~TProgressBar frees the memory associated with the TProgressBar object.

__fastcall virtual ~TProgressBar(void) { }

Description

Do not call ~TProgressBar directly. Instead, use the delete keyword on the object, which causes ~TProgressBar to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


 TPrintDialog

Hierarchy	Properties	Methods	Events	See also

TPrintDialog displays a Print dialog.

Unit

dialogs

Description

The TPrintDialog component displays a standard Windows dialog box for sending jobs to a printer. The dialog is modal and does not appear at runtime until it is activated by a call to the Execute method.


TPrintDialog properties

TPrintDialog	Alphabetically	Legend

In TPrintDialog

Collate

Copies

FromPage

MaxPage

MinPage

Options

PrintRange

PrintToFile

ToPage

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TPrintDialog properties

TPrintDialog	By object	Legend

Collate

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Copies

Ctl3D

DesignInfo

FromPage

HelpContext

MaxPage

MinPage

Name

Options

Owner

PrintRange

PrintToFile

Tag

ToPage

VCLComObject


TPrintDialog::Collate

TPrintDialog	See also

Indicates whether the Collate check box is selected.

__property bool Collate = {read=FCollate, write=FCollate, default=0};

Description

Collate is true whenever the Collate check box is selected in the Print dialog. To make the dialog open with the check box selected, set Collate to true in the Object Inspector or in program code.


TPrintDialog::Copies

TPrintDialog	See also

Indicates the number copies selected in the Print dialog.

__property int Copies = {read=FCopies, write=SetNumCopies, default=0};

Description

If Copies is 0 or 1, the dialog will have 1 in the Number of Copies field. To make the dialog open with 2 or more copies selected, set the value of Copies in the Object Inspector or in program code.


TPrintDialog::FromPage

TPrintDialog	See also 	Example

Indicates the page on which the print job is to begin.

__property int FromPage = {read=FFromPage, write=FFromPage, default=0};

Description

The FromPage property corresponds to the From field in the Print dialog.


TPrintDialog::MaxPage

TPrintDialog	See also 	Example

Determines the greatest page number the user can enter when specifying pages to print.

__property int MaxPage = {read=FMaxPage, write=FMaxPage, default=0};

Description

If the user tries to enter a number greater than MaxPage, an error message appears.

Note

The user can specify page numbers only if the poPageNums flag is set in Options. If poPageNums is on, MaxPage must be set to a value greater than MinPage or the Print dialog will not open.


TPrintDialog::MinPage

TPrintDialog	See also 	Example

Determines the smallest page number the user can enter when specifying pages to print.

__property int MinPage = {read=FMinPage, write=FMinPage, default=0};

Description

If the user tries to enter a number smaller than MinPage, a error message appears.

Note

The user can specify page numbers only if the poPageNums flag is set in Options. If poPageNums is on, MaxPage must be set to a value greater than MinPage or the Print dialog will not open.


TPrintDialog::Options

TPrintDialog	See also 	Example

Determines the appearance and behavior of the Print dialog.

enum TPrintDialogOption { poPrintToFile, poPageNums, poSelection, poWarning, poHelp, poDisablePrintToFile };

typedef Set<TPrintDialogOption, poPrintToFile, poDisablePrintToFile> TPrintDialogOptions;

__property TPrintDialogOptions Options = {read=FOptions, write=FOptions, default=0};

Description

The possible values of Options are:

Value	Meaning

poDisablePrintToFile	Disables (grays) the Print To File Check box. (Applicable only if the poPrintToFile flag is set.)

poHelp	Displays a Help button in the dialog. May not work in some versions of Windows 95.

poPageNums	Enables the Pages radio button, allowing the user to specify a page range.

poPrintToFile	Displays a Print To File check box in the dialog.

poSelection	Enables the Selection radio button, allowing the user to print selected (highlighted) text.

poWarning	Generates a warning message if the user tries to send a job to an uninstalled printer.

By default, all options flags are off.


TPrintDialog::PrintRange

TPrintDialog	See also 	Example

Indicates the type of print range selected in the dialog.

enum TPrintRange { prAllPages, prSelection, prPageNums };

__property TPrintRange PrintRange = {read=FPrintRange, write=FPrintRange, default=0};

Description

The value of PrintRange corresponds the All, Selection, and Pages (From/To) radio buttons in the Print dialog:

Value	Meaning

prAllPages	The All radio button is selected.

prSelection	The Selection radio button is selected.

prPageNums	The Pages radio button is selected.

To determine which radio button is selected by default when the dialog opens, set the value of PrintRange in the Object Inspector or in program code.

To enable the Pages radio button, set the poPageNums flag in Options. To enable the Selection radio button, set the poSelection flag in Options and set MaxPage to a greater value than MinPage.


TPrintDialog::PrintToFile

TPrintDialog	See also 	Example

Indicates whether the Print To File check box is selected.

__property bool PrintToFile = {read=FPrintToFile, write=FPrintToFile, default=0};

Description

PrintToFile is true whenever the Print To File check box is selected in the dialog. To make the dialog open with the check box selected, set PrintToFile to true in the Object Inspector or in program code.

To make the Print To File check box appear in the dialog, set the poPrintToFile flag in Options. To disable (gray) the Print To File check box, set the poDisablePrintToFile flag.


TPrintDialog::ToPage

TPrintDialog	See also 	Example

Indicates the page on which the print job is to end.

__property int ToPage = {read=FToPage, write=FToPage, default=0};

Description

The ToPage property corresponds to the To field in the Print dialog.


TPrintDialog events

TPrintDialog	Alphabetically	Legend

Derived from TCommonDialog

OnClose

OnShow


TPrintDialog events

TPrintDialog	By object	Legend

OnClose

OnShow


TPrintDialog methods

TPrintDialog	Alphabetically

In TPrintDialog

~TPrintDialog

Execute

TPrintDialog

Derived from TCommonDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPrintDialog methods

TPrintDialog	By object

~TPrintDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TPrintDialog


TPrintDialog::Execute

TPrintDialog 	Example

Displays the Print dialog box.

virtual bool __fastcall Execute(void);

Description

Execute opens the Print dialog, returning true when the user clicks Print and false when the user clicks Cancel.


TPrintDialog::TPrintDialog

TPrintDialog

TPrintDialog creates a new TPrintDialog object.

__fastcall virtual TPrintDialog(Classes::TComponent* AOwner) : Dialogs::TCommonDialog(AOwner) { }

Description

Do not call TPrintDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.


TPrintDialog::~TPrintDialog

TPrintDialog

~TPrintDialog frees the memory associated with the TPrintDialog object.

__fastcall virtual ~TPrintDialog(void) { }

Description

Do not call ~TPrintDialog directly. Instead, use the delete keyword on the object, which causes ~TPrintDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog


TPrinter

Hierarchy	Properties	Methods	See also

TPrinter encapsulates the Windows printer interface.

Unit

printers

Description

Use TPrinter to manage any printing performed by an application. Obtain an instance of TPrinter by calling the Printer function in the Printers unit.

To determine how the printed image of the form appears, use the PrintScale property of a TForm component.

A print job is started whenever any rendering is done through a Text variable or the printers canvas. This job stays open until EndDoc is called. The title displayed in the Print Manager (and on network header pages) is determined by the Title property. To start a print job, call the BeginDoc method. To end a print job that is sent successfully to the printer, call the EndDoc method. If a problem occurs and you need to terminate a print job that was not sent to the printer successfully, call the Abort method.


TPrinter properties

TPrinter	Alphabetically	Legend

In TPrinter

Aborted

Canvas

Capabilities

Copies

Fonts

Handle

Orientation

PageHeight

PageNumber

PageWidth

PrinterIndex

Printers

Printing

Title


TPrinter properties

TPrinter	By object	Legend

Aborted

Canvas

Capabilities

Copies

Fonts

Handle

Orientation

PageHeight

PageNumber

PageWidth

PrinterIndex

Printers

Printing

Title


TPrinter::Aborted

TPrinter	See also 	Example

Determines if the user aborted the print job, thereby calling the Abort method.

__property bool Aborted = {read=FAborted, nodefault};

Description

If Aborted is true, the print job was aborted. If it is false, the user did not abort the print job.


TPrinter::Canvas

TPrinter	See also 	Example

Represents the surface of the currently printing page.

__property Graphics::TCanvas* Canvas = {read=GetCanvas};

Description

Canvas represents the printing surface of a page. Use the Brush, Font, and Pen properties of the Canvas object to determine how drawing or text appears on the page.

Note:	Some printers do not support graphics. Therefore, the Draw, StretchDraw, or CopyRect methods might fail on these printers.


TPrinter::Capabilities

TPrinter

Indicates the current settings of a printer device driver.

__property TPrinterCapabilities Capabilities = {read=FCapabilities, nodefault};

Description

Capabilities contains the capabilites for the printer, indicating the orientation, number of copies, and whether or not collated is selected.


TPrinter::Copies

TPrinter

Specifies the number of copies printed.

__property int Copies = {read=GetNumCopies, write=SetNumCopies, nodefault};

Description

Copies returns information from the device mode that is set to select the number of copies printed.


TPrinter::Fonts

TPrinter	Example

Lists the fonts supported by the current printer.

__property Classes::TStrings* Fonts = {read=GetFonts};

Description

Use Fonts to get a list of the fonts supported by the printer. The list contains TrueType fonts even if the printer doesn't support them natively because the Windows Graphics Device Interface (GDI) can draw TrueType fonts accurately when a print job uses them.


TPrinter::Handle

TPrinter 	Example

Provides access to the handle of the printer object.

__property HDC Handle = {read=GetHandle, nodefault};

Description

Use Handle to gain access to the handle of the printer object.


TPrinter::Orientation

TPrinter 	Example

Determines if the print job prints vertically or horizontally on a page.

__property TPrinterOrientation Orientation = {read=GetOrientation, write=SetOrientation, nodefault}

Description

Use Orientation to determine if a print job prints in landscape or portrait.

TPrinterOrientation is the type of the Orienation property. These are the possible values for TPrinterOrientation:

Value	Meaning
poPortrait	The job prints vertically on the page.
poLandscape	The job prints horizontally on the page.


TPrinter::PageHeight

TPrinter	See also 	Example

Indicates the height (in pixels) of the currently printing page.

__property int PageHeight = {read=GetPageHeight, nodefault};

Description

Use PageHeight to find the height in pixels of the currently printing page.


TPrinter::PageNumber

TPrinter	See also 	Example

Indicates the number of the page currently printing.

__property int PageNumber = {read=FPageNumber, nodefault};

Description

Use PageNumber to find the page number of the currently printing page. PageNumber is incremented when ever the NewPage method is called.

Note:	This property is also incremented when a Text variable is written and a CR is encounted on the last line of the page.


TPrinter::PageWidth

TPrinter	See also 	Example

Indicates the value of width (in pixels) of the currently printing page.

__property int PageWidth = {read=GetPageWidth, nodefault};

Description

Use PageWidth to find the width in pixels of the currently printing page.


TPrinter::PrinterIndex

TPrinter	See also	Example

Specifies which printer listed in the Printers property is the currently selected printer.

__property int PrinterIndex = {read=GetPrinterIndex, write=SetPrinterIndex, nodefault};

Description

The value of the PrinterIndex property is the currently selected printer. If this value is changed EndDoc is called automatically::To select the default printer, set the value of PrinterIndex to -1.

The list of installed printers is found in the Printers property. The list of fonts supported by the current printer is found in the Fonts property.


TPrinter::Printers

TPrinter	See also

Lists all printers installed in Windows.

__property Classes::TStrings* Printers = {read=GetPrinters};

Description

The list of installed printers is found in the Printers property. The value of the PrinterIndex property is the currently selected printer. The list of fonts supported by the current printer is found in the Fonts property.


TPrinter::Printing

TPrinter	See also 	Example

Indicates whether a print job is printing.

__property bool Printing = {read=FPrinting, nodefault};

Description

Use Printing to determine if a job is printing.

Printing is true when the application has called the BeginDoc method, but the EndDoc method (or the Abort method) hasn't yet been called.


TPrinter::Title

TPrinter	Example

Determines the text that is listed in the Print Manager and on network header pages.

__property System::AnsiString Title = {read=FTitle, write=FTitle};

Description

Title is used by Windows in the Print Manager and for network title pages.


TPrinter methods

TPrinter	Alphabetically

In TPrinter

~TPrinter

Abort

BeginDoc

EndDoc

GetPrinter

NewPage

SetPrinter

TPrinter

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPrinter methods

TPrinter	By object

~TPrinter

Abort

BeginDoc

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EndDoc

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetPrinter

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

NewPage

SafeCallException

SetPrinter

TPrinter


TPrinter::Abort

TPrinter	See also 	Example

Terminates the printing of a print job, dropping all unprinted data.

void __fastcall Abort(void);

Description

Use Abort to terminate the print job before it completes; otherwise, use the EndDoc method.

When Abort is called, the device is then set for the next print job.


TPrinter::BeginDoc

TPrinter	See also 	Example

Sends a print job to the printer.

void __fastcall BeginDoc(void);

Description

Call BeginDoc to intitiate a print job. If the print job is sent successfully, the application calls EndDoc to end the print job. The print job won't actually start printing until EndDoc is called.


TPrinter::TPrinter

TPrinter	See also

Creates a printer.

__fastcall TPrinter(void);

Description

Never call TPrinter directly. TPrinter is called automatically by the Printer function. TPrinter allocates memory for a printer, and calls the parent object’s constructor. Then it sets the correct driver, device and port.


TPrinter::~TPrinter

TPrinter	See also

Destroys an instance of a printer.

__fastcall virtual ~TPrinter(void);

Description

Do not call ~TPrinter directly. The printer object is automatically created and destroyed.

When the ~TPrinter method is called, it checks to make sure that any currently printing job ends, then it frees resources such as the handle, fonts, canvas and so on, closes the printer and calls the parent object’s destructor.


TPrinter::EndDoc

TPrinter	See also 	Example

Ends the current print job and closes the text file variable.

void __fastcall EndDoc(void);

Description

EndDoc terminates the print job (and closes the currently open Text). The print job will being printing on the printer after a call to EndDoc.

After the application calls EndDoc, the printer begins printing. Use EndDoc after successfully sending a print job to the printer. If the print job isn't successful, use the Abort method.


TPrinter::GetPrinter

TPrinter	See also

Retrieves the current printer.

void __fastcall GetPrinter(char * ADevice, char * ADriver, char * APort, int &ADeviceMode);

Description

It is not necessary to directly call GetPrinter. Instead, access the printer in the Printers property array. For more information, see the CreateDC function in the Win32 Developer's Reference (WIN32.HLP).


TPrinter::NewPage

TPrinter	See also 	Example

Starts a new page and increments the PageNumber property.

void __fastcall NewPage(void);

Description

NewPage forces the current print job to begin printing on a new page in the printer.

NewPage increments the value of the PageNumber property. It also resets the value of the Pen property of the Canvas back to (0, 0).


TPrinter::SetPrinter

TPrinter	See also

Specifies a printer as the current printer.

void __fastcall SetPrinter(char * ADevice, char * ADriver, char * APort, int ADeviceMode);

Description

Do not call SetPrinter directly. Instead, access the the printer with the Printers property array. For more information, see the Windows API CreateDC function.


Accessibility

Read-only


Hierarchy

TObject


TPropertyEditor

Hierarchy	Properties	Methods	See also

TPropertyEditor is the base class for all property editors.

Unit

dsgnintf

Description

Use TPropertyEditor or one of its descendants as a base class when defining a property editor for a specialized property in a new component class. TPropertyEditor has several descendants that can be used to set the values of properties with simple types. Create specialized property editors to allow users to set more complicated property values from the Object Inspector.

Individual descendants of TPropertyEditor are displayed based on the type of the property being edited. Individual property editors can be associated with all properties of a specified type, or with a particular property of a particular component class. To create the association between a property editor and a property type, call RegisterPropertyEditor. Once the property editor is registered, it appears when the user attempts to edit an appropriate property using the Object Inspector.


TPropertyEditor properties

TPropertyEditor	Alphabetically 	Legend

In TPropertyEditor

Designer

PrivateDirectory

PropCount

Value


TPropertyEditor properties

TPropertyEditor	By object 	Legend

Designer

PrivateDirectory

PropCount

Value


 TPropertyEditor::Designer

TPropertyEditor	See also

Provides access to the form designer object in the IDE.

__property TFormDesigner* Designer = {read=FDesigner};

Description

Use Designer to read from or make changes to the current form or module in the IDE. The form designer has methods that can access the components in the current source file and other classes defined in included headers, create or alter the methods in the current file, and so on.


 TPropertyEditor::PrivateDirectory

TPropertyEditor

Specifies the location where the property editor can store auxiliary files.

__property System::AnsiString PrivateDirectory = {read=GetPrivateDirectory};

Description

Use PrivateDirectory to store executables used by the property editor or auxiliary files that store state information, examples, templates, and so on. PrivateDirectory is the location specified in the registry under the key:

HKEY_CURRENT_USER\Software\Borland\CBuilder\3.0\Globals\PrivateDir

The property editor can use the directory to read files, write files, or store DLLs and executables.


TPropertyEditor::PropCount

TPropertyEditor	See also

Indicates the number of components whose properties are being edited.

__property int PropCount = {read=FPropCount, nodefault};

Description

Use PropCount to determine the valid range of indexes to use when calling the GetComponent method. This value corresponds to the number of components selected when the property editor is created. Typically, it is not necessary to access individual components because the Getxxx and Setxxx methods propagate values appropriately.


TPropertyEditor::Value

TPropertyEditor	See also

Represents the current value of the property (as returned by GetValue) as a string.

__property System::AnsiString Value = {read=GetValue, write=SetValue};

Description

Read Value to determine the current property setting as it is displayed in the Object Inspector. Set Value to apply a value to all selected components for which the property is appropriate.

Note:	The Value property is implemented using the GetValue and SetValue methods. Descendants of TPropertyEditor must override these methods to implement the Value property.


TPropertyEditor methods

TPropertyEditor	Alphabetically 	Legend

In TPropertyEditor

~TPropertyEditor

Activate

AllEqual

Edit

GetAttributes

GetComponent

GetEditLimit

GetFloatValue

GetFloatValueAt

GetMethodValue

GetMethodValueAt

GetName

GetOrdValue

GetOrdValueAt

GetProperties

GetPropInfo

GetPropType

GetStrValue

GetStrValueAt

GetValue

GetValues

GetVarValue

GetVarValueAt

Initialize

Modified

Revert

SetFloatValue

SetMethodValue

SetOrdValue

SetStrValue

SetValue

SetVarValue

TPropertyEditor

ValueAvailable

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TPropertyEditor methods

TPropertyEditor	By object 	Legend

~TPropertyEditor

Activate

AllEqual

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

Edit

FieldAddress

Free

FreeInstance

GetAttributes

GetComponent

GetEditLimit

GetFloatValue

GetFloatValueAt

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetMethodValue

GetMethodValueAt

GetName

GetOrdValue

GetOrdValueAt

GetProperties

GetPropInfo

GetPropType

GetStrValue

GetStrValueAt

GetValue

GetValues

GetVarValue

GetVarValueAt

InheritsFrom

Initialize

InitInstance

InstanceSize

MethodAddress

MethodName

Modified

NewInstance

Revert

SafeCallException

SetFloatValue

SetMethodValue

SetOrdValue

SetStrValue

SetValue

SetVarValue

TPropertyEditor

ValueAvailable


TPropertyEditor::Activate

TPropertyEditor	See also

Responds when the property is selected in the Object Inspector.

virtual void __fastcall Activate(void);

Description

Do not call the Activate method. It is called automatically when the property is selected. TPropertyEditor::Activate does nothing. Override this method to determine attributes of the property dynamically when the property editor is displayed in the Object Inspector.

Before Activate is called, the GetAttributes method does not need to provide accurate information about any attributes other than paSubProperties and paMultiSelect. Any other attributes can be computed in an override of the Activate method and stored so that subsequent calls to GetAttributes can provide accurate information.


TPropertyEditor::AllEqual

TPropertyEditor	See also

Indicates whether all selected components have the same value for the property.

virtual bool __fastcall AllEqual(void);

Description

The Object Inspector calls AllEqual when there is more than one component selected to determine whether a value should appear for this property. If this method returns true, the Object Inspector displays a value for the property. If this method returns false, the line for the property in the Object Inspector remains blank.

TPropertyEditor::AllEqual always returns false if more than one selected component has the associated property. Override this method to check the properties of individual components and determine whether a property value can be displayed in the Object Inspector.

Note:	AllEqual is called only when the value returned by GetAttributes includes paMultiSelect.


TPropertyEditor::~TPropertyEditor

TPropertyEditor	See also

Destroys an instance of TPropertyEditor.

__fastcall virtual ~TPropertyEditor(void);

Description

Do not call ~TPropertyEditor. The Object Inspector destroys the property editor automatically when it is finished.

~TPropertyEditor frees the internal objects used to store information about the selected components and their property settings. Override ~TPropertyEditor to free any other internal structures created by the property editor.


TPropertyEditor::Edit

TPropertyEditor	See also

Responds when the user double-clicks the property in the Object Inspector.

virtual void __fastcall Edit(void);

Description

The Object Inspector calls Edit when the ellipses button is pressed or the property is double-clicked. The Edit method of TPropertyEditor cycles through the possible enumerated values of the property when the GetValues method returns one or more property strings to its callback method.

Override the Edit method to implement a response to the ellipses button or double-clicking the property. For example, use the Edit method to bring up a dialog for editing the property in some more meaningful fashion than typing a text value in the Object Inspector.


TPropertyEditor::GetAttributes

TPropertyEditor	See also

Describes the property so the Object Inspector provides the appropriate controls.

enum TPropertyAttribute { paValueList, paSubProperties, paDialog, paMultiSelect, paAutoUpdate, paSortList, paReadOnly, paRevertable };

typedef Set<TPropertyAttribute, paValueList, paRevertable>  TPropertyAttributes;

virtual TPropertyAttributes __fastcall GetAttributes(void);

Description

The Object Inspector calls GetAttributes to determine what controls to display for the property and what property editor methods to call. The GetAttributes method of TPropertyEditor includes paMultiSelect and paRevertable. Override GetAttributes to return the set of values that corresponds to the attributes of the associated property.

GetAttributes returns a set drawn from the following values:

Value	Meaning

paValueList	The property editor can return an enumerated list of values for the property. When paValueList is set, the GetValues method should be overridden to provide the enumerated values. When paValueList is set, the Object Inspector displays a drop-down button to the right of the property .

paSortList	The Object Inspector should sort the list returned by GetValues;

paSubProperties	The property has subproperties that are displayed indented and below the current property in standard outline format. If paSubProperties is set, the GetProperties method should be overridden to provide subproperties.

paDialog	The Edit method brings up a dialog.  When paDialog is set, the Object Inspector displays an ellipses button to the right of the property.

paMultiSelect	The property can be displayed when more than one component is selected.

paAutoUpdate	The SetValue method is called on each change made to the editor rather than after the change has been approved.

paReadOnly	Value is not allowed to change.

paRevertable	The property editor can restore the property value to the original value.  Properties that shouldn't be reverted are nested properties such as fonts and elements of composite properties such as set element values.

Note:	Before the Object Inspector calls the Activate method, GetAttributes does not need to provide accurate information about any attributes other than paSubProperties and paMultiSelect.


TPropertyEditor::GetComponent

TPropertyEditor	See also

Returns the specified object from the set of all components currently being edited by the property editor.

Classes::TPersistent* __fastcall GetComponent(int Index);

Description

Call GetComponent to access any of the objects with a property currently being edited by the property editor. The Index parameter is used to specify individual components in the internal list maintained by the property editor. Index should be a value between 0 and PropCount - 1, inclusive.

Use GetComponent to iterate over all objects currently being edited.


TPropertyEditor::GetEditLimit

TPropertyEditor	See also

Returns the maximum length, in characters, of the Value property.

virtual int __fastcall GetEditLimit(void);

Description

The Object Inspector calls GetEditLimit to determine how many characters the user can type when entering a value for the property. GetEditLimit returns 255. Override this method when the maximum length of the property string is some other value.


TPropertyEditor::GetFloatValue

TPropertyEditor	See also

Returns the property value of the first object currently being edited.

Extended __fastcall GetFloatValue(void);

Description

Call GetFloatValue to obtain the current value of the property for the first object in the internal list of objects being edited. Only call GetFloatValue if the property is a float type.

If more than one object is currently being edited, GetFloatValue returns the value for the object returned by GetComponent(0); To obtain the current property value for every object currently being edited, use the GetFloatValueAt method.


TPropertyEditor::GetFloatValueAt

TPropertyEditor	See also

Returns the property value of the specified object.

Extended __fastcall GetFloatValueAt(int Index);

Description

Call GetFloatValueAt to obtain the current value of the property for an object in the internal list of objects being edited. Only call GetFloatValueAt if the property is a float type. The Index parameter identifies which object’s value should be returned. It corresponds to the Index parameter of the GetComponent method.

Use GetFloatValueAt to iterate over all current values, for example when implementing the AllEqual method.


TPropertyEditor::GetMethodValue

TPropertyEditor	See also

Returns the property value of the first object currently being edited.

struct TMethod

{

  void *Code;

  void *Data;

} ;

Sysutils::TMethod __fastcall GetMethodValue();

Description

Call GetMethodValue to obtain the current value of the property for the first object in the internal list of objects being edited. Only call GetMethodValue if the property is a method, such as the DefWndProc property of TWinControl or an event handler.

If more than one object is currently being edited, GetMethodValue returns the value for the object returned by GetComponent(0); To obtain the current property value for every object currently being edited, use the GetMethodValueAt method.


TPropertyEditor::GetMethodValueAt

TPropertyEditor	See also

Returns the property value of the specified object.

struct TMethod

{

  void *Code;

  void *Data;

} ;

Sysutils::TMethod __fastcall GetMethodValueAt(int Index);

Description

Call GetMethodValueAt to obtain the current value of the property for an object in the internal list of objects being edited. Only call GetMethodValueAt if the property is a method, such as the DefWndProc property of TWinControl or an event handler. The Index parameter identifies which object’s value should be returned. It corresponds to the Index parameter of the GetComponent method.

Use GetMethodValueAt to iterate over all current values, for example when implementing the AllEqual method.


TPropertyEditor::GetName

TPropertyEditor

Returns the name of the property.

virtual System::AnsiString __fastcall GetName();

Description

The Object Inspector calls GetName to obtain the property name as it should appear in the Object Inspector. GetName returns the name of the property from the property type information with all underbars replaced by spaces.  Override this method if the Object Inspector should display a string other than the property name.


TPropertyEditor::GetOrdValue

TPropertyEditor	See also

Returns the property value of the first object currently being edited.

int __fastcall GetOrdValue(void);

Description

Call GetOrdValue to obtain the current value of the property for the first object in the internal list of objects being edited. Only call GetordValue if the property is an ordinal type.

If more than one object is currently being edited, GetOrdValue returns the value for the object returned by GetComponent(0); To obtain the current property value for every object currently being edited, use the GetOrdValueAt method.


TPropertyEditor::GetOrdValueAt

TPropertyEditor	See also

Returns the property value of the specified object.

int __fastcall GetOrdValueAt(int Index);

Description

Call GetOrdValueAt to obtain the current value of the property for an object in the internal list of objects being edited. Only call GetOrdValueAt if the property is an ordinal type. The Index parameter identifies which object’s value should be returned. It corresponds to the Index parameter of the GetComponent method.

Use GetOrdValueAt to iterate over all current values, for example when implementing the AllEqual method.


TPropertyEditor::GetProperties

TPropertyEditor	See also

Provides the subproperties of the property to a callback procedure.

typedef void __fastcall (__closure *TGetPropEditProc)(TPropertyEditor* Prop);

virtual void __fastcall GetProperties(TGetPropEditProc &Proc);

Description

The Object Inspector calls GetProperties when the property is expanded to show sub-properties. The GetProperties method of TPropertyEditor does nothing. Property editors that return paSubProperties from the GetAttributes method should override GetProperties to create an appropriate property editor and pass it to the Proc parameter for every sub-property (or nested property) of the property.


TPropertyEditor::GetPropInfo

TPropertyEditor	See also

Returns the property information record for the object being edited.

Typinfo::PPropInfo __fastcall GetPropInfo(void);

Description

Call GetPropInfo to obtain access to the property information record that describes the property being edited and its access functions.  If more than one object is being edited, GetPropInfo returns the property information record for the object returned by GetComponent(0).

Note:	If only the type information record is desired (indirectly pointed to by the PropType field), use the GetPropType method instead.


TPropertyEditor::GetPropType

TPropertyEditor	See also

Returns the type information record for the object being edited.

Typinfo::PTypeInfo __fastcall GetPropType(void);

Description

Call GetPropType to obtain access to the  type information record that describes the property being edited.  If more than one object is being edited, GetPropType returns the  type information record for the object returned by GetComponent(0).

If information about the property access functions and storage details is desired as well, use the GetPropInfo method instead.


TPropertyEditor::GetStrValue

TPropertyEditor	See also

Returns the property value of the first object currently being edited.

System::AnsiString __fastcall GetStrValue();

Description

Call GetStrValue to obtain the current value of the property for the first object in the internal list of objects being edited. Only call GetStrValue if the property is a string type.

If more than one object is currently being edited, GetStrValue returns the value for the object returned by GetComponent(0); To obtain the current property value for every object currently being edited, use the GetStrValueAt method.


TPropertyEditor::GetStrValueAt

TPropertyEditor	See also

Returns the property value of the specified object.

System::AnsiString __fastcall GetStrValueAt(int Index);

Description

Call GetStrValueAt to obtain the current value of the property for an object in the internal list of objects being edited. Only call GetStrValueAt if the property is an ordinal type. The Index parameter identifies which object’s value should be returned. It corresponds to the Index parameter of the GetComponent method.

Use GetStrValueAt to iterate over all current values, for example when implementing the AllEqual method.


TPropertyEditor::GetValue

TPropertyEditor	See also

Returns the value string displayed by the Object Inspector.

virtual System::AnsiString __fastcall GetValue();

Description

The Object Inspector calls GetValue to obtain the string  it uses to display the property value. TPropertyEditor::GetValue returns the string “(unknown)”.  Override this method to provide an appropriate string for the value currently represented in the object inspector.

GetValue is called to read the Value property.


TPropertyEditor::GetValues

TPropertyEditor	See also

Provides the enumerated values of the property to a callback procedure.

typedef void __fastcall (__closure *TGetStrProc)(const System::AnsiString S);

virtual void __fastcall GetValues(Classes::TGetStrProc &Proc);

Description

The Object Inspector calls GetValues when the drop-down button is clicked to show enumerated values. The GetValues method of TPropertyEditor does nothing. Property editors that return paValueList from the GetAttributes method should override GetValues to call the Proc parameter for every string that can represent a valid enumerated value. Even if the GetAttributes method does not return paValueList, proprety editors for enumerated types should still override GetValues to enumerate all possible values.


TPropertyEditor::GetVarValue

TPropertyEditor	See also

Returns the property value of the first object currently being edited.

System::Variant __fastcall GetVarValue();

Description

Call GetVarValue to obtain the current value of the property for the first object in the internal list of objects being edited. Only call GetVarValue if the property value can be represented by a variant.

If more than one object is currently being edited, GetVarValue returns the value for the object returned by GetComponent(0); To obtain the current property value for every object currently being edited, use the GetVarValueAt method.


TPropertyEditor::GetVarValueAt

TPropertyEditor	See also

Returns the property value of the specified object.

System::Variant __fastcall GetVarValueAt(int Index);

Description

Call GetVarValueAt to obtain the current value of the property for an object in the internal list of objects being edited. Only call GetVarValueAt if the property value can be represented as a variant. The Index parameter identifies which object’s value should be returned. It corresponds to the Index parameter of the GetComponent method.

Use GetVarValueAt to iterate over all current values, for example when implementing the AllEqual method.


TPropertyEditor::Initialize

TPropertyEditor	See also

Initializes the property editor after it is created but before it is used.

virtual void __fastcall Initialize(void);

Description

Do not call the Initialize method. It is called automatically by the Object Inspector to allow property editors to perform any necessary initialization before they are used. The Initialize method of TPropertyEditor does nothing.

Override the Initialize method to perform any special initialization, such as the creation of helper objects. Many times property editors are created and discarded without being used because they do not represent a common property across all selected components.  Initialize is called after it is determined the property editor is going to be used by the object inspector and not just thrown away. Initializing property values and creating helper objects in the Initialize method rather than the constructor improves performance by preventing a lot of unnecessary work.


TPropertyEditor::Modified

TPropertyEditor	See also

Informs the designer the property value changes.

void __fastcall Modified(void);

Description

Call Modified after changing the property value so that the designer is aware that something has changed.

Note:	It is not necessary to call Modified if changes are made using the SetFloatValue, SetMethodValue, SetOrdValue, SetStrValue, or SetVarValue methods. These methods automatically call Modified.


TPropertyEditor::Revert

TPropertyEditor	See also

Restores all object properties to their original values.

void __fastcall Revert(void);

Description

Call Revert to restore the original property values that each of the edited objects had before the user began making modification with the Object Inspector. Revert will not work if GetAttributes returns paAutoUpdate.


TPropertyEditor::SetFloatValue

TPropertyEditor	See also

Changes the property value for every object being edited.

void __fastcall SetFloatValue(Extended Value);

Description

Call SetFloatValue to change the property setting for every object that can be returned by the GetComponent method. Do not call SetFloatValue unless the property is represents a float value. After changing a property value using SetFloatValue, it is not necessary to call Modified.


TPropertyEditor::SetMethodValue

TPropertyEditor	See also

Changes the property value for every object being edited.

struct TMethod

{

  void *Code;

  void *Data;

} ;

void __fastcall SetMethodValue(const Sysutils::TMethod &Value);

Description

Call SetMethodValue to change the property setting for every object that can be returned by the GetComponent method. Do not call SetMethodValue unless the property represents a method. After changing a property value using SetMethodValue, it is not necessary to call Modified.


TPropertyEditor::SetOrdValue

TPropertyEditor	See also

Changes the property value for every object being edited.

void __fastcall SetOrdValue(int Value);

Description

Call SetOrdValue to change the property setting for every object that can be returned by the GetComponent method. Do not call SetOrdValue unless the property represents an ordinal value. After changing a property value using SetOrdValue, it is not necessary to call Modified.


TPropertyEditor::SetStrValue

TPropertyEditor	See also

Changes the property value for every object being edited.

void __fastcall SetStrValue(const System::AnsiString Value);

Description

Call SetStrValue to change the property setting for every object that can be returned by the GetComponent method. Do not call SetStrValue unless the property represents a string value. After changing a property value using SetStrValue, it is not necessary to call Modified.


TPropertyEditor::SetValue

TPropertyEditor	See also

Responds when the user changes the value of the property.

virtual void __fastcall SetValue(const System::AnsiString Value);

Description

Do not call SetValue. It is called automatically by the object inspector when the user has finished changing the property value. The SetValue method for TPropertyEditor does nothing. Descendant classes override SetValue to apply the value entered by the user (represented by the Value parameter) to all components that can be returned by the GetComponent method.

For many property editors, SetValue only needs to translate the Value string into an appropriate value and call SetFloatValue, SetMethodValue, SetOrdValue, SetStrValue, or SetVarValue. For properties that do not correspond to a float, method, ordinal, string, or variant, however, SetValue must directly propagate the new value to every component and then call the Modified method. If the value can’t be set, SetValue should raise an exception that describes the problem.

Note:	If the property is only changed through a dialog brought up by the Edit method, SetValue need not be overridden.


TPropertyEditor::SetVarValue

TPropertyEditor	See also

Changes the property value for every object being edited.

void __fastcall SetVarValue(const System::Variant &Value);

Description

Call SetVarValue to change the property setting for every object that can be returned by the GetComponent method. Do not call SetVarValue unless the property can be represented by a variant value. After changing a property value using SetVarValue, it is not necessary to call Modified.


TPropertyEditor::ValueAvailable

TPropertyEditor	See also

Indicates whether all components being edited have a value for the property if their ComponentStyle includes csCheckPropAvail.

bool __fastcall ValueAvailable(void);

Description

The Object Inspector calls ValueAvailable to determine which components can be edited for a particular property or which properties can be displayed for a particular component.


Accessibility

Read-only


TPropertyEditor::TPropertyEditor

TPropertyEditor

Creates a new TPropertyEditor object.

__fastcall TPropertyEditor(TFormDesigner* ADesigner, int APropCount);

Description

Do not create instances of a property editor. Registered property editors are created automatically for selected objects in the forms designer.


Scope

Protected


Hierarchy

TObject


TPropertyPage

Hierarchy	Properties	Methods	Events	See also

TPropertyPage is an abstract class that implements a property page for an ActiveX control.

Unit

axctrls

Description

TPropertyPage extends TCustomForm by adding the functionality needed to embed the form in an ActiveX property page dialog. It also adds methods to copy property values from the object to the form’s controls, and vice versa.

To implement your own property page for an ActiveX object, derive a new class from TPropertyPage, design the form, then override the UpdateObject and UpdatePropertyPage methods.  The C++Builder IDE provides an expert for creating a skeleton property page.

TPropertyPage provides a helper method, Modified, that your form can call when any of the controls on the form are changed by the user.  Calling the Modified method notifies the property dialog that the user has modified the object’s properties.  Normally this will enable the Apply button on the property dialog.

The property page maintains a connection to the object it is editing, using the OleObject property.  This property is a Variant and can be used to read and write the object’s properties.


TPropertyPage properties

TPropertyPage	Alphabetically	Legend

In TPropertyPage

OleObject

Derived from TCustomForm

Active

ActiveControl

ActiveOleControl

Canvas

ClientHeight

ClientRect

ClientWidth

Designer

DropTarget

KeyPreview

Menu

ModalResult

OleFormObject

Parent

PixelsPerInch

PrintScale

Scaled

Visible

WindowState

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

Color

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

ParentFont

PopupMenu

ShowHint

Top

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TPropertyPage properties

TPropertyPage	By object	Legend

Active

ActiveControl

ActiveOleControl

Align

AutoScroll

BoundsRect

Brush

Canvas

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

Designer

DesignInfo

DropTarget

Enabled

Font

Handle

Height

HelpContext

Hint

HorzScrollBar

KeyPreview

Left

Menu

ModalResult

Name

OleFormObject

OleObject

Owner

Parent

ParentFont

ParentWindow

PixelsPerInch

PopupMenu

PrintScale

Scaled

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

VertScrollBar

Visible

Width

WindowProc

WindowState


TPropertyPage::OleObject

TPropertyPage	See also

Contains a reference to the ActiveX control being edited by the page.

__property System::OleVariant OleObject = {read=FOleObject};

Description

Cast the value of OleObject to the appropriate interface, such as IUnknown or IDispatch, and use the methods of the interface to access the property values and methods of the control.


TPropertyPage events

TPropertyPage	Alphabetically	Legend

Derived from TCustomForm

OnActivate

OnClose

OnCreate

OnDeactivate

OnDestroy

OnHide

OnPaint

OnResize

OnShow

Derived from TWinControl

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TPropertyPage events

TPropertyPage	By object	Legend

OnActivate

OnClick

OnClose

OnCreate

OnDblClick

OnDeactivate

OnDestroy

OnDragDrop

OnDragOver

OnHide

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnPaint

OnResize

OnShow


TPropertyPage methods

TPropertyPage	Alphabetically

In TPropertyPage

~TPropertyPage

EnumCtlProps

Modified

TPropertyPage

UpdateObject

UpdatePropertyPage

Derived from TCustomForm

Close

CloseQuery

DefocusControl

FocusControl

GetFormImage

Hide

Print

Release

SendCancelMode

SetFocus

SetFocusedControl

Show

ShowModal

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPropertyPage methods

TPropertyPage	By object

~TPropertyPage

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

Close

CloseQuery

ContainsControl

ControlAtPos

DefaultHandler

DefocusControl

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

EnumCtlProps

FieldAddress

FindComponent

FocusControl

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetFormImage

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

Modified

NewInstance

PaintTo

Perform

Print

Realign

Refresh

Release

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendCancelMode

SendToBack

SetBounds

SetFocus

SetFocusedControl

SetTextBuf

Show

ShowModal

TPropertyPage

Update

UpdateControlState

UpdateObject

UpdatePropertyPage


TPropertyPage::EnumCtlProps

TPropertyPage	See also

Looks for a PropType type property in a control on the form.

void __fastcall EnumCtlProps(const GUID &PropType, Classes::TStrings* PropNames);

Description

Use EnumCtlProps to locate all properties of the ActiveX object specified by OleObject that use the GUID specified by the PropType parameter.  The names of all properties of the specified type are added to the PropNames list.  The property names can be used subsequently to read or write property values using the IDispatch interface of the ActiveX object.

Note

EnumCtlProps does not clear the PropNames list before adding property names.  Applications should clear the string list before calling EnumCtlProps to avoid mistaking entries that were previously in the list for properties of the ActiveX object.


TPropertyPage::Modified

TPropertyPage

Modified is a helper method that notifies the property page’s container that the user has edited one of the controls on the page.

void __fastcall Modified(void);

Description

Call Modified from the controls on the property page when their values change. The property dialog will enable the Apply button in response to this method call.


TPropertyPage::UpdatePropertyPage

TPropertyPage	See also

UpdatePropertyPage copies the property values from the ActiveX object to controls on the property page.

virtual void __fastcall UpdatePropertyPage(void);

Description

This method is normally called when the property page is first shown, or when the user undoes changes to the property dialog box.  The UpdatePropertyPage method implemented by TPropertyPage does nothing.  Override this method to copy the property values from the ActiveX object to the controls on the property page.

UpdatePropertyPage is the reverse of UpdateObject, which copies the property values from controls on the property page to the ActiveX object.


TPropertyPage::UpdateObject

TPropertyPage	See also

UpdateObject is called to copy property values from the controls on the form to the ActiveX Object.

virtual void __fastcall UpdateObject(void);

Description

Override this method to copy values from the controls on the property page to properties of the ActiveX Object.  Cast the value of the OleObject property to an IDispatch interface to set the property values.

UpdateObject is the reverse of UpdatePropertyPage, which copies the property values from the ActiveX Object to controls on the form.


TPropertyPage::TPropertyPage

TPropertyPage

TPropertyPage creates a new TPropertyPage object.

__fastcall virtual TPropertyPage(Classes::TComponent* AOwner);


TPropertyPage::~TPropertyPage

TPropertyPage

~TPropertyPage frees the memory associated with the TPropertyPage object. Do not call ~TPropertyPage directly. Instead, use the delete keyword on the object, which causes ~TPropertyPage to be invoked automatically.

__fastcall virtual ~TPropertyPage(void);


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm


 TProvider

Hierarchy	Properties	Methods	Events	See also

TProvider provides data from a BDE-dataset to a client dataset in a multi-tiered application.

Unit

bdeprov

Description

TProvider is usually placed in the application server of a multi-tiered application.  It serves as a data broker and conduit between a remote database application server and a client dataset in the desktop client application. The provider offers an IProvider interface that is an intermediate link between the client dataset on the client, and a TQuery, TStoredProc, or TTable object on the application server. It packages data from the server dataset and passes it in data packets to the client dataset.

The client dataset receives the data packets, and reconstructs them to create a local, in-memory copy of the data for user access. When user access is complete, the client dataset repackages any changed data and sends the updates to the provider on the application server. The provider applies the updates to the remote database server, resolves record conflicts where possible, and sends all unresolved records back to the client dataset for further reconciliation.

Most applications do not use the properties and methods of TProvider directly.  Instead, a client dataset in the client application accesses these through the IProvider interface.  Most applications will only use the TProvider events directly.

The application server does not need to include a provider object for BDE-enabled datasets because they have their own IProvider interfaces.  However, using a provider gives the application server greater control by surfacing events to which the application server can respond.

Note:	See the MSTRDTL demo and the ADHOC demo for examples of how to use TProvider. See the USQLPROV demo for an example of deriving a custom TProvider component.


TProvider properties

TProvider	Alphabetically	Legend

In TProvider

DataSet

Derived from TCustomProvider

Constraints

Provider

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TProvider properties

TProvider	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Constraints

Data

DataSet

DesignInfo

Name

Owner

Provider

Tag

VCLComObject


TProvider::DataSet

TProvider	See also 	Example

Specifies the Borland Database Engine (BDE) dataset component on the application server from which the provider gets data and to which it posts client application updates.

__property Dbtables::TDBDataSet* DataSet = {read=FDataSet, write=FDataSet};

Description

Set DataSet to the name of a dataset component in a data module on the application server. The specified dataset component is used by the provider to get data from the database server to which the component is connected, and to write client application updates to the database server.

DataSet must be a BDE-enabled dataset component, either one of the ones provided in the Object and Component Library (TTable, TStoredProc, TQuery), or a custom component derived from TDBDataSet.


TProvider events

TProvider	Alphabetically	Legend

In TProvider

OnGetData

OnUpdateData

OnUpdateError

Derived from TCustomProvider

OnDataRequest


TProvider events

TProvider	By object	Legend

OnDataRequest

OnGetData

OnUpdateData

OnUpdateError


TProvider::OnGetData

TProvider	See also 	Example

Occurs after a provider retrieves data but before it is sent to the client.

typedef void __fastcall (__closure *TProviderDataEvent)(Dbclient::TClientDataSet* DataSet);

__property TProviderDataEvent OnGetData = {read=FOnGetData, write=FOnGetData};

Description

Write an OnGetData event handler to perform any custom data processing the provider should handle before returning data to a client. The OnGetData event occurs after a provider fetches data from its dataset but before the data is sent on to the client. Using the methods of the DataSet parameter, data can be edited in the OnGetData event handler before sending it to the client.


TProvider::OnUpdateData

TProvider	See also 	Example

Occurs when a provider begins to apply updates.

typedef void __fastcall (__closure *TProviderDataEvent)(Dbclient::TClientDataSet* DataSet);

__property TProviderDataEvent OnUpdateData = {read=FOnUpdateData, write=FOnUpdateData};

Description

Write an OnUpdateData event to handle special processing before the provider actually applies updates received from the client to a database. Using the methods belonging to the DataSet parameter, an application can

•	Examine data (for example, for values or data changes that should not permitted), and throw exceptions that cancel applying of updates before they occur.

•	Change data (for example encrypting or decrypting values) before it is sent on to the database server.


TProvider::OnUpdateError

TProvider	See also 	Example

Occurs when a provider attempts to update a record but cannot because of an error condition.

enum TResolverResponse { rrSkip, rrAbort, rrMerge, rrApply, rrIgnore };

enum TUpdateKind { ukModify, ukInsert, ukDelete };

typedef void __fastcall (__closure *TResolverErrorEvent)(Dbclient::TClientDataSet* DataSet, EUpdateError* E, Db::TUpdateKind UpdateKind, TResolverResponse &Response);

__property TResolverErrorEvent OnUpdateError = {read=FOnUpdateError, write=FOnUpdateError};

Description

Write an OnUpateError event handler to respond to error conditions that arise when the provider applies a client dataset’s updates to the database server. The OnUpdateError event handler is called for each record that can’t be updated.

DataSet is the name of a temporary client dataset to use for accessing data during the update process. Use the OldValue, NewValue, and CurValue properties of the dataset’s field components to view the changed fields and determine the cause of the problem.

Warning	The code in an OnUpdateError handler must not call any methods that make a different record the current one.

E is a pointer to a EUpdateError object from which an application can extract an error message and the actual cause of the error condition. The OnUpdateError handler can use this information to determine how to respond to the error condition.

UpdateKind describes the type of update that generated the error. The following table lists the possible values for UpdateKind and what they indicate:

Value	Meaning

ukModify	Editing an existing record caused an error.

ukInsert	Inserting or appending a new record caused an error.

ukDelete	Deleting an existing record raised an error.

Response indicates the action to take when the OnUpdateError handler exits. On entry into the handler, Response is set to either rrAbort or rrSkip, based on the MaxErrors parameter passed to the ApplyUpdates function that triggers OnUpdateError. If MaxErrors is 0 then Response is rrAbort; otherwise it is rrSkip. If OnUpdateError can handle or correct the error, set Response to rrCorrect before exiting the error handler. The following table lists the possible values for Response and what they indicate:

Value	Meaning

rrSkip	Skips updating the record that raised the error condition, and leaves the unapplied changes in the cache.

rrAbort	Aborts the operation without displaying an error message.

rrMerge	Merges the changed record with the record in the database

rrCorrect	Corrects the record in the database with this record

rrApply	Applies the corrected updated to the database.

rrIgnore	Ignores the error condition and does not apply the record.


TProvider methods

TProvider	Alphabetically

In TProvider

~TProvider

ApplyUpdates

GetRecords

Reset

SetParams

TProvider

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TProvider methods

TProvider	By object

~TProvider

ApplyUpdates

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetRecords

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

Reset

SafeCallException

SetParams

TProvider


TProvider::ApplyUpdates

TProvider	See also

Applies updates received from a client dataset to datasets connected to a remote database server.

virtual System::OleVariant __fastcall ApplyUpdates(const System::OleVariant &Delta, int MaxErrors, int &ErrorCount);

Description

Call ApplyUpdates to write a client’s updates to a database server. Delta is a variant array containing the updated, inserted, and deleted records from the client to write to the database. MaxErrors indicates the maximum number of errors to permit before aborting the update operation. ErrorCount indicates the actual number of errors encountered during the update operation. If ErrorCount is greater than MaxErrors, or the OnUpdateError event returns rrAbort for a record it cannot resolve, all updates that have been successfully applied so far are rolled back, and the update process is aborted.

If you provide an OnUpdateError event handler for the provider, it is called automatically whenever a record in Delta cannot be updated. The OnUpdateError handler gives you a chance to correct the error condition and try again before returning an unsuccessfully updated record back to the client dataset. Records that cannot be updated are stored in a results array that is converted and returned to the client dataset for further reconciliation after all records are processed.

ApplyUpdates returns a variant that is a data packet containing all records that could not be applied to the database.


TProvider::TProvider

TProvider	See also

Creates an instance of a TProvider component.

__fastcall virtual TProvider(Classes::TComponent* AOwner);

Description

Call TProvider indirectly, using the new keyword, to instantiate a provider component at runtime. If you place a provider component in a data module for an application server at design time, it is created automatically for you at runtime.

TProvider calls its parent class’s constructor, points to a BDE-enabled dataset component if such a dataset owns the provider, and sets the Constraints property to true.


TProvider::GetRecords

TProvider	See also

Retrieves a specified number of records from a provider’s dataset.

virtual System::OleVariant __fastcall GetRecords(int Count, int &RecsOut);

Description

Call GetRecords to retrieve a specified number of records from the provider’s dataset. Count indicates the number of records to retrieve. If Count is –1, all records are retrieved. If Count is 0, only metadata records are retrieved. RecsOut indicate the actual number of records retrieved. GetRecords returns a Variant containing a data packet.

A client application calls a provider’s GetRecords method to retrieve a partial set of all available records from a dataset. GetRecords is especially useful when dealing with very large datasets, or when working with datasets that have blob fields.


TProvider::Reset

TProvider	See also

Enables a provider to start fetching sequential packets of records from the start of the dataset.

virtual void __fastcall Reset(Word MetaData);

Description

Ordinarily, the provider fetches sequential packets of records from the database server. If the server contains 100 records, and the provider fetches 10 records at a time (based on a client’s request), then the first fetch retrieves records 1 to 10, the second 11 to 20, and so on.

Call Reset to force a provider to start fetching packets of records from the start of the dataset again. Otherwise each fetch operation starts at the record following the last record fetched in the previous call to GetRecords.

MetaData indicates whether or not the next call to fetch records should include metadata. Set MetaData to true if this is the first time the client is fetching data from the provider.  Otherwise, the client will raise an exception when it tries to use the data.  Set MetaData to false if the client has already fetched data from the provider.  For example, when working with a master/detail data model, MetaData should be true only if this is the first detail set the provider is retrieving.  Every subsequent detail set should begin with a call to Reset so that all the records in the detail set are retrieved, but the MetaData should not be refetched after the first data packet.

Note:	When fetching data packets that do not contain metadata (after setting the MetaData parameter to false), the client dataset should use the AppendData method, which assumes that the metadata is already known.


TProvider::SetParams

TProvider	See also

Enables parameter values to be passed to a provider.

virtual void __fastcall SetParams(const System::OleVariant &Values);

Description

Call SetParams to pass parameter values to a provider component. Values is a variant containing the parameters to pass. If the dataset to which parameters are sent is a TQuery or TStoredProc component, parameters are bound to the Params property of the component. If the dataset to which parameters are sent is a TTable component, parameters are used to set a range for the table.

Values can be in one of three forms:

•	To pass a single parameter, Values is a singe value.

•	To pass multiple parameters without parameter names, Values is a Variant array containing the values to use.

•	To pass one or more named parameters, Values is a Variant array where each element of the array contains a parameter name and a parameter value.  This option allows clients to make changes to a selection of parameters out of a larger possible number of parameters.

For example, if the DataSet property refers to a query, the lines

Variant Temp[2];

Temp[0] = Variant(1232);

Temp[1] = Variant("Unisco");

Provider1->SetParams(VarArrayOf(Temp,1));

are equivalent to making the assignments

((TQuery *)(Provider1->DataSet))->Params->Items[0]->Value = Variant(1231);

((TQuery *)(Provider1->DataSet))->Params->Items[1]->Value = Variant("Unisco").

When assigning parameters by name, rather than position, SetParams takes a variant array of variant arrays. Thus, if the dataset property refers to a query, the lines

Variant PData = VarArrayCreate(OPENARRAY(int,(0,1)),varVariant);

Variant Temp[2];

Temp[0] = Variant("CustNo");

Temp[1] = Variant(1231);

PData[0] = VarArrayOf(Temp,1);

Temp[0] = Variant("Company");

Temp[1] = Variant("Unisco");

PData[1] = VarArrayOf(Temp,1);

Provider1->SetParams(PData);

are equivalent to writing

((TQuery *)(Provider1->DataSet))->ParamByName("CustNo")->Value = Variant(1231);

((TQuery *)(Provider1->DataSet))->ParamByName("Company")->Value = Variant("Unisco")

Note:	Calling SetParams automatically calls the Reset method, so that the next packet of records fetched from the provider begin at the start of the dataset.


TProvider::~TProvider

TProvider

Frees the memory associated with the TProvider object.

__fastcall virtual ~TProvider(void) { }

Description

Do not call ~TProvider directly. Instead, use the delete keyword on the object, which causes ~TProvider to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomProvider


 TPrinterSetupDialog

Hierarchy	Properties	Methods	Events	See also

TPrinterSetupDialog displays a Print Setup dialog for configuring printers.

Unit

dialogs

Description

TPrinterSetupDialog displays a modal Windows dialog box for configuring printers. The contents of the dialog vary depending on the printer driver selected.

The dialog does not appear at runtime until it is activated by a call to the Execute method.


TPrinterSetupDialog properties

TPrinterSetupDialog	Alphabetically	Legend

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TPrinterSetupDialog properties

TPrinterSetupDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DesignInfo

HelpContext

Name

Owner

Tag

VCLComObject


TPrinterSetupDialog events

TPrinterSetupDialog	Alphabetically	Legend

Derived from TCommonDialog

OnClose

OnShow


TPrinterSetupDialog events

TPrinterSetupDialog	By object	Legend

OnClose

OnShow


TPrinterSetupDialog methods

TPrinterSetupDialog	Alphabetically

In TPrinterSetupDialog

~TPrinterSetupDialog

Execute

TPrinterSetupDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TPrinterSetupDialog methods

TPrinterSetupDialog	By object

~TPrinterSetupDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TPrinterSetupDialog


TPrinterSetupDialog::Execute

TPrinterSetupDialog

Displays the printer configuration dialog box.

virtual bool __fastcall Execute(void);

Description

Execute opens the Print Setup dialog. If the user clicks OK, Execute configures the printers as specified in the dialog and returns true. If the user clicks Cancel, Execute returns false.


TPrinterSetupDialog::TPrinterSetupDialog

TPrinterSetupDialog

TPrinterSetupDialog creates a new TPrinterSetupDialog object.

__fastcall virtual TPrinterSetupDialog(Classes::TComponent* AOwner) : Dialogs::TCommonDialog(AOwner) { }

Description

Do not call TPrinterSetupDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.


TPrinterSetupDialog::~TPrinterSetupDialog

TPrinterSetupDialog

~TPrinterSetupDialog frees the memory associated with the TPrinterSetupDialog object.

__fastcall virtual ~TPrinterSetupDialog(void) { }

Description

Do not call ~TPrinterSetupDialog directly. Instead, use the delete keyword on the object, which causes ~TPrinterSetupDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog


 TQuery

Hierarchy	Properties	Methods	Events	See also

TQuery encapsulates a dataset with a result set that is based on an SQL statement.

Unit

dbtables

Description

Use TQuery to access a database using SQL statements. Query components can be used with remote database servers such as Sybase, SQL Server, Oracle, Informix, DB2, and InterBase, with Paradox, dBASE, Access, and FoxPro, and with ODBC-compliant databases.

Query components are useful because they can

•	Access more than one table at a time (called a “join” in SQL).

•	Automatically access a subset of rows and columns in its underlying table(s), rather than always returning all rows and columns.

Note:	TQuery is of particular importance to the development of scalable database applications. If there is any chance that an application built to run against local databases will be scaled to a remote SQL database server in the future, use TQuery components from the start to ensure easier scaling later.


TQuery properties

TQuery	Alphabetically	Legend

In TQuery

Constrained

DataSource

Local

ParamCheck

ParamCount

Params

Prepared

RequestLive

RowsAffected

SQL

SQLBinary

StmtHandle

Text

UniDirectional

Derived from TDBDataSet

Database

DatabaseName

DBHandle

DBLocale

DBSession

Provider

SessionName

UpdateMode

Derived from TBDEDataSet

CacheBlobs

CachedUpdates

CanModify

ExpIndex

Filter

Filtered

FilterOptions

Handle

KeySize

Locale

RecNo

RecordCount

RecordSize

UpdateObject

UpdateRecordTypes

UpdatesPending

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

Constraints

DefaultFields

Designer

EOF

FieldCount

FieldDefs

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TQuery properties

TQuery	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CacheBlobs

CachedUpdates

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Constrained

Constraints

Database

DatabaseName

DataSource

DBHandle

DBLocale

DBSession

DefaultFields

Designer

DesignInfo

EOF

ExpIndex

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Handle

KeySize

Local

Locale

Modified

Name

Owner

ParamCheck

ParamCount

Params

Prepared

Provider

RecNo

RecordCount

RecordSize

RequestLive

RowsAffected

SessionName

SQL

SQLBinary

State

StmtHandle

Tag

Text

UniDirectional

UpdateMode

UpdateObject

UpdateRecordTypes

UpdatesPending

VCLComObject


TQuery::Constrained

TQuery	See also

Indicates whether updates and inserts that don’t conform to the result set generated by a SELECT statement are permitted for Paradox and dBASE tables

__property bool Constrained = {read=FConstrained, write=FConstrained, default=0};

Description

Use Constrained to determine whether or not edits and insertions are permitted to a Paradox or dBASE table underlying a result set when the UPDATE or INSERT statements contain one or more values that do not comply with the WHERE clause conditions of the SELECT statement that generated the result set. Constrained only applies to live result sets. Constraints are enforced during the editing process.

If Constrained is false (the default), updates and inserts are permitted regardless of the SELECT statement criteria. If true, updates and inserts are not permitted if they violate the criteria of the SELECT statement that generated the result set.

For example, if Constrained is true and a query component’s SQL property is

SELECT *

FROM CUSTOMERS

WHERE (CUSTNO > 1400) AND (CUSTNO < 1500)

then the user would not be allowed to enter a value for CustNo that fell outside this range of values.


TQuery::DataSource

TQuery	See also	Example

Specifies the data source component from which to extract current field values to use to bind otherwise unassigned parameters in the query’s SQL statement.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Set the DataSource property to the name of a data source component from which to extract current field values to use to bind otherwise unassigned parameters in the SQL statement in this component’s SQL property. DataSource must point to another dataset; it cannot point to this query component.

The dataset specified in DataSource must be created, populated, and opened before attempting to bind parameters. Parameters are bound by calling the query’s Prepare method prior to executing the query.

Tip:	DataSource is especially of use when creating a master-detail relationship between tables using a linked query. It is also of use to guarantee binding for parameters that are not already set in the Params property or through a call to the ParamByName method.

If the SQL statement used by a query does not contain parameters, or all parameters are bound by the application using the Params property or the ParamByName method, DataSource need not be assigned.


TQuery::Local

TQuery	See also	Example

Indicates whether a query references one or more Paradox or dBASE tables rather than SQL tables on a remote server.

__property bool Local = {read=FLocal, nodefault};

Description

Check Local to determine if a query accesses one or more Paradox or dBASE tables rather than SQL tables. If Local is true, then the query only accesses dBASE or Paradox. Otherwise Local is false. Local is set automatically when an application calls the query’s Prepare method prior to executing the query.

Some query component settings, such as Constrained, are only meaningful for queries against Paradox and dBASE tables. Others are only meaningful for queries against remote SQL servers. Local can provide useful information for branching logic in code based on the type of database accessed. It can also be used to determine whether or not the BDE parsed a query using its local query engine rather than passing SQL statements directly to a remote server.


TQuery::ParamCheck

TQuery	See also

Specifies whether the parameter list for a query is regenerated if the SQL property changes at runtime.

__property bool ParamCheck = {read=FParamCheck, write=FParamCheck, default=1};

Description

Set ParamCheck to specify whether or not the Params property is cleared and regenerated if an application modifies the query’s SQL property at runtime. By default ParamCheck is true, meaning that the Params property is automatically regenerated at runtime. When ParamCheck is true, the proper number of parameters is guaranteed to be generated for the current SQL statement.

This property is most useful for data definition statements that use parameters (for example, when using a query component to create an InterBase stored procedure).

An application that does not use parameterized queries may choose to set ParamCheck to false, but otherwise ParamCheck should be true.


TQuery::ParamCount

TQuery	See also 	Example

Indicates the current number of parameters for the query.

__property Word ParamCount = {read=GetParamsCount, nodefault};

Description

Check ParamCount to determine how many parameters are in the Params property. If the ParamCheck property is true, ParamCount always corresponds to the number of actual parameters in the SQL statement for the query.

An application can add or delete parameters to the Params property. Such additions and deletions are automatically reflected in ParamCount.


TQuery::Params

TQuery	See also 	Example

Contains the parameters for a query’s SQL statement.

__property TParams* Params = {read=FParams, write=SetParamsList};

Description

Access Params at runtime to view and set parameter names, values, and data types dynamically (at design time use the Query Parameters editor to set parameter information). Params is a zero-based array of parameter records. Index specifies the array element to access.

Note:	An easier way to set and retrieve parameter values when the name of each parameter is known is to call ParamByName. ParamByName cannot, however, be used to change a parameter’s data type or name.

Parameters used in SELECT statements cannot be NULL, but they can be NULL for UPDATE and INSERT statements.


TQuery::Prepared

TQuery	See also 	Example

Determines whether or not a query is prepared for execution.

__property bool Prepared = {read=FPrepared, write=SetPrepare, nodefault};

Description

Examine Prepared to determine if a query is already prepared for execution. If Prepared is true, the query is prepared, and if Prepared is false, the query is not prepared. While a query need not be prepared before execution, execution performance is enhanced if the query is prepared beforehand, particularly if it is a parameterized query that is executed more than once using the same parameter values.

Note:	An application can change the current setting of Prepared to prepare or unprepare a query. If Prepared is true, setting it to false calls the Unprepare method to unprepare the query. If Prepared is false, setting it to true calls the Prepare method to prepare the query. Generally, however, it is better programming practice to call Prepare and Unprepare directly. These methods automatically update the Prepared property.


TQuery::RequestLive

TQuery	See also

Specifies whether an application expects to receive a live result set from the Borland Database Engine (BDE) when the query executes.

__property bool RequestLive = {read=FRequestLive, write=FRequestLive, default=0};

Description

Set RequestLive to specify whether or not the BDE should attempt to return a live result set to the application. RequestLive is false by default, meaning that a query returns a read-only result set.

Set RequestLive to true to request a live result set. Setting RequestLive to true does not guarantee that a live result set is returned by the BDE. The BDE returns a live result set only if the SELECT syntax of the query conforms to the syntax requirements for a live result set.

Setting RequestLive to true will not return a live result set if the query contains any of the following:

•	A JOIN clause against a remote dataset or against more than two local tables.

•	A JOIN clause that is not a left-to right outer join, can’t be satisfied by existing indexes, or specifies output order.

•	A UNION, INTERSECT, or MINUS clause.

•	A DISTINCT clause in the SELECT statement.

•	Aggregate functions.

•	A GROUPBY or HAVING clause.

•	Correlated subqueries or Subqueries that reference the table in the FROM clause.

•	An ORDER BY clause not based on an index.

•	Base tables or views that are not updatable.

•	Field names that include SQL reserved words.

If RequestLive is true, but the syntax does not conform to the requirements, the BDE returns a read-only result set for Paradox or dBASE, or an error return code for remote servers.


TQuery::RowsAffected

TQuery	See also

Returns the number of rows operated upon by the latest query execution.

__property int RowsAffected = {read=GetRowsAffected, nodefault};

Description

Check RowsAffected to determine how many rows were updated or deleted by the last query operation. If RowsAffected is -1, the query did not update or delete any rows.


TQuery.SQL

TQuery	See also 	Example

Contains the text of the SQL statement to execute for the query.

__property Classes::TStrings* SQL = {read=FSQL, write=SetQuery};

Description

Use SQL to provide the SQL statement that a query component executes when its ExecSQL or Open method is called. At design time the SQL property can be edited by invoking the String List editor in the Object Inspector.

The SQL property may contain only one complete SQL statement at a time. In general, multiple “batch” statements are not allowed unless a particular server supports them.

The SQL property can be used to access

•	Paradox or dBASE tables, using local SQL. The allowable syntax is a subset of ANSI-standard SQL and includes SELECT, INSERT, UPDATE, and DELETE statements.

•	Databases on the Local InterBase Server, using standard SQL-92 and specific InterBase extensions to SQL syntax. For information on syntax and limitations, see the InterBase Language Reference.

•	Databases on remote database servers (C++Builder Client/Server only) using the appropriate SQL Links driver. Any standard statement in the server's SQL dialect is allowed. For information on SQL syntax and limitations, see the server documentation.

The SQL statement provided to SQL may contain replaceable parameters, following standard SQL-92 syntax conventions. Parameters are created and stored in the Params property.

To provide an SQL statement at runtime:

1	Call Close to shut down the query if it is currently active.

2	Call Clear to empty the SQL property.

3	Call Add to specify the new text, or call LoadFromFile to assign the text in an SQL script file to the SQL property.

4	Use the ParamByName method to set up any parameters for the query, if it uses them.

5	Call Prepare to ready the query for execution.

6	Call ExecSQL or Open to execute the query.

Note:	Developers with the Client/Server suite can also invoke the Visual Query Builder to create an SQL statement for execution.


TQuery::SQLBinary

TQuery	See also

Points to the binary data stream that represents an SQL query statement or result set.

__property char * SQLBinary = {read=FSQLBinary, write=FSQLBinary};

Description

Do not access SQLBinary. It is an internal binary data stream used by the query component to communicate directly with the Borland Database Engine. To access or set the SQL statement that this query component executes, use the SQL property. To access or set the parameters used in a parameterized SQL statement, use the Params property.


TQuery::StmtHandle

TQuery

Identifies the Borland Database Engine (BDE) statement handle for the query.

__property Bde::hDBIStmt StmtHandle = {read=FStmtHandle};

Description

Retrieve StmtHandle if an application makes a direct call to the BDE, bypassing the methods of TQuery. Some BDE API calls require a statement handle as a parameter. Under all other circumstances an application does not need to access this property.


TQuery::Text

TQuery	See also

Points to the actual text of the SQL query passed to the Borland Database Engine (BDE).

__property System::AnsiString Text = {read=FText};

Description

Text is a read-only property that can be examined to determine the actual contents of SQL statement passed to the BDE. For parameterized queries, Text contains the SQL statement with parameters replaced by the parameter substitution symbol (?)

In general there should be no need to examine the Text property. To access or change the SQL statement for the query, use the SQL property. To examine or modify parameters, use the Params property.


TQuery::UniDirectional

TQuery

Determines whether or not Borland Database Engine (BDE) bidirectional cursors are enabled for a query’s result set.

__property bool UniDirectional = {read=FUniDirectional, write=FUniDirectional, default=0};

Description

Set UniDirectional to control whether or not a BDE cursor can move forward and backward through a result set. By default UniDirectional is false, enabling forward and backward navigation.

Note:	Traditionally SQL cursors are unidirectional. They can travel only forward through a dataset. The BDE, however, permits bidirectional travel by caching records. If an application does not need bidirectional access to records in a result set, set UniDirectional to true. When UniDirectional is true, an application requires less memory and performance is improved.


TQuery events

TQuery	Alphabetically	Legend

Derived from TBDEDataSet

OnServerYield

OnUpdateError

OnUpdateRecord

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TQuery events

TQuery	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnServerYield

OnUpdateError

OnUpdateRecord


TQuery methods

TQuery	Alphabetically

In TQuery

~TQuery

ExecSQL

ParamByName

Prepare

TQuery

UnPrepare

Derived from TDBDataSet

CheckOpen

CloseDatabase

OpenDatabase

Derived from TBDEDataSet

ApplyUpdates

BookmarkValid

Cancel

CancelUpdates

CommitUpdates

CompareBookmarks

ConstraintCallBack

DisableConstraints

EnableConstraints

FetchAll

GetCurrentRecord

GetIndexInfo

Locate

Lookup

RevertRecord

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Post

Prior

Refresh

Resync

SetFields

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TQuery methods

TQuery	By object

~TQuery

ActiveBuffer

Append

AppendRecord

ApplyUpdates

Assign

BookmarkValid

Cancel

CancelUpdates

CheckBrowseMode

CheckOpen

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CommitUpdates

CompareBookmarks

ConstraintCallBack

ControlsDisabled

CursorPosChanged

DefaultHandler

Delete

DestroyComponents

Destroying

DisableConstraints

DisableControls

Dispatch

Edit

EnableConstraints

EnableControls

ExecSQL

FetchAll

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindLast

FindNext

FindPrior

First

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GotoBookmark

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

Last

Locate

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

ParamByName

Post

Prepare

Prior

Refresh

RemoveComponent

Resync

RevertRecord

SafeCallException

SetFields

TQuery

Translate

UnPrepare

UpdateCursorPos

UpdateRecord

UpdateStatus


TQuery::TQuery

TQuery	See also

Creates an instance of a query component.

__fastcall virtual TQuery(Classes::TComponent* AOwner);

Description

Call TQuery to instantiate a query at runtime. Query components placed in forms or data modules at design time are created automatically.

TQuery calls its parent object’s constructor constructor, creates an empty SQL statement list, an empty parameter list, sets the OnChange event handler for the SQL statement list, establishes a data link, sets the RequestLive property to false, sets the ParamCheck property to true, and sets the RowsAffected property to -1.


TQuery::~TQuery

TQuery	See also

Destroys the instance of a query.

__fastcall virtual ~TQuery(void);

Description

Do not call ~TQuery directly. Instead call Free to verify that the query is not already freed before calling ~TQuery. ~TQuery disconnects from the server, frees the SQL statement list, the parameter list, and the data link and SQL binary storage area, and then calls its parent object’s destructor.


TQuery::ExecSQL

TQuery	See also 	Example

Executes the SQL statement for the query.

void __fastcall ExecSQL(void);

Description

Call ExecSQL to execute the INSERT, UPDATE, or DELETE statement currently assigned to the SQL property. ExecSQL is also used to execute data definition statements.

Note:	For SELECT statements, call Open instead of ExecSQL.

ExecSQL prepares the statement in SQL property for execution if it has not already been prepared. To speed performance, an application should ordinarily call Prepare before calling ExecSQL for the first time.


TQuery::ParamByName

TQuery	See also 	Example

Accesses parameter information based on a specified parameter name.

TParam* __fastcall ParamByName(const System::AnsiString Value);

Description

Call ParamByName to set or use parameter information for a specific parameter based on its name. Value is the name of the parameter for which to retrieve information. ParamByName is used to set an parameter’s value at runtime. For example, the following statement retrieves the current value of a parameter called “Contact” into an edit box:

Parameters used in SELECT statements cannot be NULL, but they can be NULL for UPDATE and INSERT statements.


TQuery::Prepare

TQuery	See also 	Example

Sends a query to the Borland Database Engine (BDE) and the server for optimization prior to execution.

void __fastcall Prepare(void);

Description

Call Prepare to have the BDE and a remote database server allocate resources for the query and to perform additional optimizations. Calling Prepare before executing a query improves application performance.

C++Builder automatically prepares a query if it is executed without first being prepared. After execution, C++Builder unprepares the query. When a query will be executed a number of times, an application should always explicitly prepare the query to avoid multiple and unnecessary prepares and unprepares.

Preparing a query consumes some database resources, so it is good practice for an application to unprepare a query once it is done using it. The UnPrepare method unprepares a query.

Note:	When you change the text of a query at runtime, the query is automatically closed and unprepared.


TQuery::UnPrepare

TQuery	See also

Frees the resources allocated for a previously prepared query.

void __fastcall UnPrepare(void);

Description

Call UnPrepare to free the resources allocated for a previously prepared query on the server and client sides.

Preparing a query consumes some database resources, so it is good practice for an application to unprepare a query once it is done using it. The UnPrepare method unprepares a query.

Note:	When you change the text of a query at runtime, the query is automatically closed and unprepared.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet

TBDEDataSet

TDBDataSet


 TQueryTableProducer

Hierarchy	Properties	Methods	Events	See also

TQueryTableProducer assembles a sequence of HTML commands to display the result set of a query in a tabular format.

Unit

dbweb

Description

Use TQueryTableProducer to produce an HTML table for the records of a parameterized query. The TQuery object obtains its parameters from an HTTP request message. If the request is a GET message, the parameters for the query are the QueryFields property of the request object. If the request is a POST message, the parameters for the query are the ContentFields property of the request object.

To produce an HTML table for a query that has no parameters, use the TDataSetTableProducer object instead.

Note:	See the WebServ demo for an example of how to use TQueryTableProducer.


TQueryTableProducer properties

TQueryTableProducer	Alphabetically	Legend

In TQueryTableProducer

DataSet

Query

Derived from TDSTableProducer

Caption

CaptionAlignment

Columns

Editor

Footer

Header

MaxRows

RowAttributes

TableAttributes

Derived from TCustomContentProducer

Dispatcher

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TQueryTableProducer properties

TQueryTableProducer	By object	Legend

Caption

CaptionAlignment

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataSet

DesignInfo

Dispatcher

Editor

Footer

Header

MaxRows

Name

Owner

Query

RowAttributes

TableAttributes

Tag

VCLComObject


TQueryTableProducer::DataSet

TQueryTableProducer	See also

Specifies the TQuery object that TQueryTableProducer uses to obtain its data.

__property Db::TDataSet* DataSet = {read=GetDataSet, write=SetDataSet};

Description

Set DataSet to specify the query that is run to obtain the data for the HTML table. Use DataSet to set the query for the TQueryTableProducer rather than the DataSource property: TQueryTableProducer generates its data source internally.

The individual field bindings specified by the THTMLTableColumn objects in the Columns property refer to fields in DataSet.

Note:	DataSet is identical to the Query property, except the query object is viewed as a TDataSet type.


TQueryTableProducer::Query

TQueryTableProducer	See also 	Example

Specifies the TQuery object that TQueryTableProducer runs to obtain its data.

__property Dbtables::TQuery* Query = {read=FQuery, write=SetQuery};

Description

Set Query to specify the query to run to obtain the data for the HTML table. Use Query to set the query for the TQueryTableProducer rather than the DataSource property: TQueryTableProducer generates its data source internally.

The individual field bindings specified by the THTMLTableColumn objects in the Columns property refer to fields in DataSet.

Note:	Query is identical to the DataSet property, except Query does not use the TDataSet base class of the query object.


TQueryTableProducer events

TQueryTableProducer	Alphabetically	Legend

Derived from TDSTableProducer

OnCreateContent

OnFormatCell

OnGetTableCaption


TQueryTableProducer events

TQueryTableProducer	By object	Legend

OnCreateContent

OnFormatCell

OnGetTableCaption


TQueryTableProducer methods

TQueryTableProducer	Alphabetically

In TQueryTableProducer

~TQueryTableProducer

Content

TQueryTableProducer

Derived from TDSTableProducer

BeginUpdate

EndUpdate

Derived from TCustomContentProducer

ContentFromStream

ContentFromString

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TQueryTableProducer methods

TQueryTableProducer	By object

~TQueryTableProducer

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Content

ContentFromStream

ContentFromString

DefaultHandler

DestroyComponents

Destroying

Dispatch

EndUpdate

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TQueryTableProducer


TQueryTableProducer::Content

TQueryTableProducer	See also 	Example

Returns the HTML representation of the query results.

virtual System::AnsiString __fastcall Content(void);

Description

Call Content to run the query with the parameters taken from the HTTP request message and retrieve the resulting HTML representation. If the MethodType of the request is mtGet, the parameters for the query are the QueryFields property of the request. If the MethodType of the request is mtPost, the parameters for the query are the ContentFields property of the request.

After running the query, Content calls the OnCreateContent event handler. If the OnCreateContent event handler indicates that the Content method should continue, Content returns the Header property, followed by an HTML table image of the records in the query, followed by the Footer property. If the OnCreateContent event handler indicates that the Content method should not continue, Content returns an empty string.

The string returned by Content can be used as the Content property of the response object associated with the request message.


TQueryTableProducer::TQueryTableProducer

TQueryTableProducer

Creates a new TQueryTableProducer object.

__fastcall virtual TQueryTableProducer(Classes::TComponent* AOwner) : Dbweb::TDSTableProducer(AOwner) { }

Description

Do not call TQueryTableProducer directly when creating a query table producer at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created TQueryTableProducer object. Query table producers placed in a web module at design time are created automatically.

Pass a single Component as a parameter to provide the TQueryTableProducer object with an Owner that is responsible for freeing it. This is usually the Web module or dispatcher that is also used as the value of the Dispatcher property.


TQueryTableProducer::~TQueryTableProducer

TQueryTableProducer

~TQueryTableProducer frees the memory associated with the TQueryTableProducer object.

__fastcall virtual ~TQueryTableProducer(void) { }

Description

Do not call ~TQueryTableProducer directly. Instead, use the delete keyword on the object, which causes ~TQueryTableProducer to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomContentProducer

TDSTableProducer


 TRadioButton

Hierarchy	Properties	Methods	Events	See also

TRadioButton is a wrapper for a Windows radio button.

Unit

stdctrls

Description

Use TRadioButton to add a radio button to a form. Use radio buttons to present a set of mutually exclusive options to the user—that is, only one radio button in a set can be selected at any time. When the user selects a radio button, the previously selected radio button becomes unselected. Radio buttons are frequently grouped in a radio group box (TRadioGroup). Add the group box to the form first, then choose the radio buttons from the Component palette and put them in the group box.

By default, all radio buttons that are directly contained by the same windowed control container, such as a TRadioGroup or TPanel, are grouped. For example, two radio buttons on a form can be checked at the time only if they are contained in separate containers, such as two different group boxes.


TRadioButton properties

TRadioButton	Alphabetically	Legend

In TRadioButton

Alignment

Checked

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TRadioButton properties

TRadioButton	By object	Legend

Align

Alignment

BoundsRect

Brush

Caption

Checked

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TRadioButton::Alignment

TRadioButton	See also

Determines the position of the caption relative to the radio button.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

typedef TAlignment TLeftRight;

__property Classes::TLeftRight Alignment = {read=FAlignment, write=SetAlignment, default=1};

Description

Set Alignment to determine where the caption of the radio button should appear. These are the possible values:

Value	Meaning

taLeftJustify	The caption appears to the left of the radio button.

taRightJustify	The caption appears to the right of the radio button.

Note:	Do not confuse the Alignment property with the alignment of the caption in the text area of the radio button. The caption always appears left-aligned. Alignment only controls on which side of the button the text area appears.


TRadioButton::Checked

TRadioButton	See also 	Example

Determines whether the option represented by the radio button is selected.

__property bool Checked = {read=FChecked, write=SetChecked, default=0};

Description

Read Checked to determine whether the radio button is selected. Set Checked to true to select the radio button and deselect all other radio buttons in the same container. Set Checked to false to deselect the radio button, leaving no radio button in the group selected.


TRadioButton events

TRadioButton	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TRadioButton events

TRadioButton	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TRadioButton methods

TRadioButton	Alphabetically

In TRadioButton

~TRadioButton

TRadioButton

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRadioButton methods

TRadioButton	By object

~TRadioButton

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TRadioButton

Update

UpdateControlState


TRadioButton::TRadioButton

TRadioButton	See also

Creates an instance of TRadioButton.

__fastcall virtual TRadioButton(Classes::TComponent* AOwner);

__fastcall TRadioButton(HWND ParentWindow) : Stdctrls::TButtonControl(ParentWindow) { }

Description

Call TRadioButton indirectly, using the new keyword, to instantiate a radio button at runtime. Radio buttons added to forms at design time are created automatically.

Pass a single Component as a parameter to provide the radio button with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the radio button in a non-VCL window. This syntax is used when the button is implemented as an ActiveX control that is embedded in a non-VCL window.

TRadioButton calls the parent class’s constructor, then sets the initial values for the radio button, such as the Width and Height property values to 113 pixels and 17 pixels, respectively, the ControlStyle set to csSetCaption and csDoubleClicks, and the Alignment property value to taLeftJustify.


TRadioButton::~TRadioButton

TRadioButton

~TRadioButton frees the memory associated with the TRadioButton object.

__fastcall virtual ~TRadioButton(void) { }

Description

Do not call ~TRadioButton directly. Instead, use the delete keyword on the object, which causes ~TRadioButton to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TButtonControl


 TRadioGroup

Hierarchy	Properties	Methods	Events	See also

TRadioGroup represents a group of radio buttons that function together.

Unit

extctrls

Description

A TRadioGroup object is a special group box that contains only radio buttons. Radio buttons that are placed directly in the same control component are said to be “grouped.” When the user checks a radio button, all other radio buttons in its group become unchecked. Hence, two radio buttons on a form can be checked at the same time only if they are placed in separate containers, such as group boxes.

To add radio buttons to a TRadioGroup, edit the Items property in the Object Inspector. Each string in Items makes a radio button appear in the group box with the string as its caption. The value of the ItemIndex property determines which radio button is currently selected.

Display the radio buttons in a single column or in multiple columns by setting the value of the Columns property.


TRadioGroup properties

TRadioGroup	Alphabetically	Legend

Derived from TCustomRadioGroup

Columns

ItemIndex

Items

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TRadioGroup properties

TRadioGroup	By object	Legend

Align

BoundsRect

Brush

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

Columns

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

ItemIndex

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TRadioGroup events

TRadioGroup	Alphabetically	Legend

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TRadioGroup events

TRadioGroup	By object	Legend

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnStartDrag


TRadioGroup methods

TRadioGroup	Alphabetically

In TRadioGroup

~TRadioGroup

TRadioGroup

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRadioGroup methods

TRadioGroup	By object

~TRadioGroup

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TRadioGroup

Update

UpdateControlState


TRadioGroup::TRadioGroup

TRadioGroup

TRadioGroup creates a new TRadioGroup object.

__fastcall virtual TRadioGroup(Classes::TComponent* AOwner) : Extctrls::TCustomRadioGroup(AOwner) { }

__fastcall TRadioGroup(HWND ParentWindow) : Extctrls::TCustomRadioGroup(ParentWindow) { }

Description

Do not call TRadioGroup directly. Instead, use the keyword new, which returns an indirect reference to the new radio group. TRadioGroup objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the radio group with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the radio group in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the radio group is implemented as an ActiveX control.


TRadioGroup::~TRadioGroup

TRadioGroup	See also

~TRadioGroup frees the memory associated with the TRadioGroup object.

__fastcall virtual ~TRadioGroup(void) { }

Description

Do not call ~TRadioGroup directly. Instead, use the delete keyword on the object, which causes ~TRadioGroup to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGroupBox

TCustomRadioGroup


TReader

Hierarchy	Properties	Methods	Events	See also

TReader is a specialized filer object that reads component data from an associated stream.

Unit

classes

Description

TReader is used internally by the VCL streaming system to restore the state of a component that has been written to a stream. It handles the mechanics of reading the data associated with a component from the stream. The reader object, rather than the stream object, is responsible for handling the complexities of streaming components. These include methods for:

•	Creating component instances from class names read from the stream.

•	Assigning stream data to published component properties.

•	Enabling an object to store hidden or complex data as if they were published properties of the object.

•	Resolving references between components, such as when a property refers to another component.

Other methods and properties of TReader trigger the reader object's events and interaction with the stream.

Applications do not directly create reader objects. Readers are automatically created in a stream object’s methods or in global routines that initiate the component streaming process. These include:

•	the global routine ObjectBinaryToText procedure, which directly creates a reader object.

•	the global ReadComponentResFile function, which creates a file stream that creates a reader object.

•	the TStream::ReadComponent method, which creates a reader object.

Once the streaming process is underway applications do not need to directly manipulate reader objects. The interaction between the reader, component, and stream objects happens automatically in methods of these objects that make calls to each other.


TReader properties

TReader	Alphabetically	Legend

In TReader

Owner

Parent

Position

Derived from TFiler

Ancestor

IgnoreChildren

Root


TReader properties

TReader	By object	Legend

Ancestor

IgnoreChildren

Owner

Parent

Position

Root


TReader::Owner

TReader	See also

Stores the component that is assigned as the Owner property of components read from the reader object's stream.

__property TComponent* Owner = {read=FOwner, write=FOwner};

Description

Owner is used internally by the VCL streaming system to determine which components to stream. All components owned by the Root component are handled by the streaming process.

Owner is the Owner property of the component read from the stream. The component’s Owner property is assigned its value from the reader’s Owner property. If the value of the reader’s Owner property is NULL, then the Root property is assigned as the component’s Owner property.

For most components, Owner is NULL. For components that can contain subcomponents which are not owned by the Root form, such as the nodes of a tree view component, the Owner is not the same as the Root. The GetChildOwner method of the component determines the Owner.


TReader::Parent

TReader	See also

Stores the component that is assigned as the Parent property of controls read from the reader’s stream.

__property TComponent* Parent = {read=FParent, write=FParent};

Description

Parent is used internally by the VCL streaming system. The value of the Parent property is determined by the order that components are read from the stream. The Parent relationship determines the visual containment of components.


TReader::Position

TReader	See also

Represents the current reading position in the associated stream.

__property int Position = {read=GetPosition, write=SetPosition, nodefault};

Description

Position is used to track the reader’s position within the stream. The value of Position will always be inside the most recent buffer block read. Thus, for reading, Position will always be less than the stream's Position.


TReader events

TReader	Alphabetically

In TReader

OnAncestorNotFOund

OnError

OnFindMethod

OnReferenceName

OnSetName


TReader events

TReader	By object

OnAncestorNotFOund

OnError

OnFindMethod

OnReferenceName

OnSetName


TReader::OnAncestorNotFound

TReader	See also

Occurs when the object from which a streamed object is derived can’t be found.

typedef void __fastcall (__closure *TAncestorNotFoundEvent)(TReader* Reader, const System::AnsiString ComponentName, System::TMetaClass* ComponentClass, TComponent* &Component);

__property TAncestorNotFoundEvent OnAncestorNotFound = {read=FOnAncestorNotFound, write=FOnAncestorNotFound};

Description

OnAncestorNotFound is for internal use.


TReader::OnError

TReader	See also

Occurs when a reader object encounters an error reading its data, such as reading the name of an undeclared property or an illegal value.

typedef void __fastcall (__closure *TReaderError)(TReader* Reader, const System::AnsiString Message, bool &Handled);

__property TReaderError OnError = {read=FOnError, write=FOnError};

Description

OnError is used internally by the C++Builder environment to report errors. It can also be used to write an event handler to selectively choose to process or ignore errors.

The last parameter passed to the OnError event handler, Handled, is passed by reference. By default, the Error method passes false in Handled, but a handler that corrects the error or chooses to ignore the error can set Handled to true, which prevents further processing of the error. If the event handler returns with Handler still set to false, the reader object throws an EReadError exception.


TReader::OnFindMethod

TReader	See also

Occurs each time the reader object reads an event, which is a method-pointer property, for an object.

typedef void __fastcall (__closure *TFindMethodEvent)(TReader* Reader, const System::AnsiString MethodName, void * &Address, bool &Error);

__property TFindMethodEvent OnFindMethod = {read=FOnFindMethod, write=FOnFindMethod};

Description

OnFindMethod is used internally by the C++Builder environment for reading events. It can also be used to write a handler to ask the user how to handle missing methods.

If the reader cannot locate the named method assigned to the method pointer, it sets the Error parameter of the OnFindMethod handler to true. The handler can set Error to false, which prevents FindMethod from throwing an exception when the handler returns.


TReader::OnReferenceName

TReader	See also

Occurs when resolving references to other objects such as when one object is the property value of another.

typedef void __fastcall (__closure *TReferenceNameEvent)(TReader* Reader, System::AnsiString &Name);

__property TReferenceNameEvent OnReferenceName = {read=FOnReferenceName, write=FOnReferenceName};

Description

OnReferenceName is for internal use only.


TReader::OnSetName

TReader	See also

Occurs just before the reader object sets the Name property of a component it reads from its stream.

typedef void __fastcall (__closure *TSetNameEvent)(TReader* Reader, TComponent* Component, System::AnsiString &Name);

__property TSetNameEvent OnSetName = {read=FOnSetName, write=FOnSetName};

Description

OnSetName is used by internally by the C++Builder environment to handle duplicate names of components and forms. It can also be used to write an event handler to perform special processing just before the Name property is set for the component which has just been created and is about to have its properties read from the stream.

The Name parameter to the OnSetName event handler passed by reference, so the handler can change the name before the reader assigns it to the component. For example, OnSetName is useful for filtering all the component names in a form, to add or change part of the string.


TReader methods

TReader	Alphabetically	Legend

In TReader

~TReader

BeginReferences

CopyValue

DefineBinaryProperty

DefineProperty

EndOfList

EndReferences

Error

FindAncestorComponent

FindMethod

FixupReferences

FlushBuffer

NextValue

Read

ReadBoolean

ReadChar

ReadCollection

ReadComponent

ReadComponents

ReadFloat

ReadIdent

ReadInteger

ReadListBegin

ReadListEnd

ReadPrefix

ReadRootComponent

ReadSignature

ReadStr

ReadString

ReadValue

ReferenceName

SetName

TReader

Derived from TFiler

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TReader methods

TReader	By object	Legend

~TReader

BeginReferences

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyValue

DefaultHandler

DefineBinaryProperty

DefineProperty

Dispatch

EndOfList

EndReferences

Error

FieldAddress

FindAncestorComponent

FindMethod

FixupReferences

FlushBuffer

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

NextValue

Read

ReadBoolean

ReadChar

ReadCollection

ReadComponent

ReadComponents

ReadFloat

ReadIdent

ReadInteger

ReadListBegin

ReadListEnd

ReadPrefix

ReadRootComponent

ReadSignature

ReadStr

ReadString

ReadValue

ReferenceName

SafeCallException

SetName

TReader


TReader::BeginReferences

TReader	See also

Starts a block of commands that read components that might contain references to other components.

void __fastcall BeginReferences(void);

Description

Do not call BeginReferences directly. BeginReferences is used internally in C++Builder for streaming properties that reference other components.

Following the call to BeginReferences, the reader object creates a list of all the objects read and their names. After all of the interdependent objects are read, FixupReferences is called to resolve the named references from the stream into instance references. Finally, call EndReferences to dispose of the fixup list.

BeginReferences is always used together with FixupReferences and EndReferences in a try...__finally block.


TReader::CopyValue

TReader

Copies data while reading components.

void __fastcall CopyValue(TWriter* Writer);

Description

Do not call CopyValue, it is used internally by the C++Builder environment.


TReader::DefineBinaryProperty

TReader	See also

Defines binary data the reader object reads as if the data were a published property.

typedef void __fastcall (__closure *TStreamProc)(TStream* Stream);

virtual void __fastcall DefineBinaryProperty(const System::AnsiString Name, TStreamProc &ReadData, TStreamProc &WriteData, bool HasData);

Description

DefineBinaryProperty is called internally by the DefineProperties method of an object that has data it needs to store. Applications can call DefineBinaryProperty directly when overriding the DefineProperties method of a component with large custom data (like a bitmap). This is the only context in which DefineBinaryProperty (or DefineProperty) should be used.

DefineProperties takes a generic filer object as its parameter. For reading binary data, DefineProperties takes a TReader object and calls its DefineBinaryProperty method. DefineBinaryProperty then reads the property’s name data and passes the data to the indicated ReadData method.

The Name parameter specifies the name of the “fake” property to be read from the stream. A “fake” property is a property that is not published, and that exists only in the code for the DefineBinaryProperty method. The Top and Left properties of a non-visual component are examples of “fake” properties. These are also called “defined properties” or “custom defined properties::”

The TStreamProc type is the type of the ReadData and WriteData parameters. It is the method-pointer type that points to a procedure (defined in the component object) that reads or writes a binary representation of the object's data directly to or from the stream passed to them in the Stream parameter. For TReader the WriteData parameter is ignored.

The HasData parameter determines at run time whether the "fake" property has data to store (write). For TReader the HasData parameter is ignored.

Defined binary properties are rare. VCL objects that store graphics as binary data are the most common use of filer objects to store and retrieve binary data. More commonly, objects use the DefineProperty method. The difference between DefineBinaryProperty and DefineProperty is that when using DefineBinaryProperty, the component reads the binary property directly from a memory stream, rather than going through the filer object. Binary data is also harder to edit as text.

Note:	Streamable objects that are descended from TPersistent inherit a DefineProperties method, however DefineProperties does nothing until TComponent. Therefore, it is a component’s DefineProperties method that calls the reader’s DefineBinaryProperty when reading binary data.


TReader::DefineProperty

TReader	See also

Defines data the reader object reads as if it were a published property.

typedef void __fastcall (__closure *TReaderProc)(TReader* Reader);

typedef void __fastcall (__closure *TWriterProc)(TWriter* Writer);

virtual void __fastcall DefineProperty(const System::AnsiString Name, TReaderProc &ReadData, TWriterProc &WriteData, bool HasData);

Description

DefineProperty is called internally by the DefineProperties method of an object that has data it needs to store. DefineProperties takes a generic filer object as its parameter. For reading data DefineProperties takes a TReader object and then calls the DefineProperties method of the reader object. DefineProperty then reads the property’s name and it’s data.

The Name parameter specifies the name of the “fake” property to be read from the stream.

The TReaderProc type is the type of the ReadData parameter. It is the method-pointer type that points to a procedure (defined in the storing object) which reads the object's data that represents a property value to the reader object. For TReader the WriteData parameter is ignored.

The HasData parameter determines at run time whether the "fake" property has data to store (write). For TReader the HasData parameter is ignored.

The difference between DefineBinaryProperty and DefineProperty is that the binary property is read directly from a stream, rather than going through a filer object, and binary data is harder to edit as text.


TReader::~TReader

TReader	See also

Moves the current position of the stream back to the beginning before calling the parent class’s destructor.

__fastcall virtual ~TReader(void);

Description

Do not call ~TReader directly. Reader objects are created indirectly through the methods or routines that use them. These methods and routines handle freeing the TReader object.


TReader::EndOfList

TReader	See also

Indicates the end of a group of items that are sequentially read from the stream.

bool __fastcall EndOfList(void);

Description

EndOfList is used by other methods that iterate through a list of items when reading in data. It checks for a value type that signals the end of that type of data. EndOfList returns true if the reader object has read to the end of a list of items.

When reading a list of items, the reader object calls ReadListBegin method, then the items are repeatedly read until EndOfList returns true. Finally, the reader calls ReadListEnd.

Note:	Component writers can use this in their defined property ReadData methods, as, for example, with TStrings.


TReader::EndReferences

TReader	See also

Terminates a block of code that reads components from the reader object's stream that might contain references to each other.

void __fastcall EndReferences(void);

Description

EndReferences is used for streaming properties that reference another component. Programmers should not need to call EndReferences directly.

The reader object calls EndReferences and creates a list of all the objects read and their names. After all the interdependent objects are read, FixupReferences is called to resolve the named references from the stream into instance references. Finally, call EndReferences to dispose of the fixup list.

EndReferences is always used in the finally part of a try...__finally block that also includes calls to BeginReferences and FixupReferences.


TReader::Error

TReader	See also

Generates an OnError event.

virtual bool __fastcall Error(const System::AnsiString Message);

Description

The reader object calls Error whenever it encounters a problem reading a component or a property. By default, Error sets its return value to false, then calls any handler attached to the OnError event, which can change the return value.

Use Error to change the return value that indicates whether to continue error processing. A return value of true indicates that the application should continue to treat the condition as an error. A return value of false indicates that the error condition is either fixed or should be ignored.

Note:	This method is virtual only for the design-time environment. Programmers would not create descendent classes of a TReader object.


TReader::FindAncestorComponent

TReader	See also

Locates an ancestor component with a specified name.

virtual TComponent* __fastcall FindAncestorComponent(const System::AnsiString Name, System::TMetaClass* ComponentClass);

Description

TReader objects use FindAncestorComponent internally to determine the ancestroy of an object that is being read into memory. FindAncestorComponent locates the ancestor component with the specified name and class, and returns the corresponding component object. If the ancestor object has not already been read into memory, FindAncestorComponent generates an OnAncestorNotFound event to allow the appropriate event handler to locate the ancestor.


TReader::FindMethod

TReader	See also

Returns a pointer to a method for a specified component.

virtual void * __fastcall FindMethod(TComponent* Root, const System::AnsiString MethodName);

Description

FindMethod is used by the reader object when it reads a property that is a method pointer (that is, usually an event). After reading the name of the assigned method (the event handler), the reader calls FindMethod to get the address of the method in the root object (the form).

FindMethod returns a pointer to the method, for the component passed in Root, that has the name passed in MethodName. Then it calls the event handler attached to the OnFindMethod event, if any. If FindMethod cannot locate the named method and the OnFindMethod handler does not clear its error flag, FindMethod throws an EReadError exception.

To customize the processing of method pointers read from the reader object, write an event handler for OnFindMethod.


TReader::FixupReferences

TReader	See also

Resolves references when streaming properties that are represented by another component.

void __fastcall FixupReferences(void);

Description

FixupReferences is used internally by the VCL streaming system to resolve the named references from the stream into instance references. Users would never need to call this method.

The reader object calls BeginReferences and creates a list of all the objects read and their names. After all the interdependent objects are read, FixupReferences is called to resolve the references among various mutually dependent components read from the reader object's stream after all of the objects have been read. Finally, call EndReferences to dispose of the fixup list.

FixupReferences is always used inside a try...__finally block between calls to BeginReferences and EndReferences.


TReader::FlushBuffer

TReader	See also

Synchronizes the reader’s buffer with its stream’s buffer.

virtual void __fastcall FlushBuffer(void);

Description

FlushBuffer synchronizes the reader's buffer with the associated stream by setting the stream’s Position to match the reader’s Position.


TReader::NextValue

TReader	See also

Returns the type of the next item in the reader object's stream without moving the position of the stream.

enum TValueType { vaNull, vaList, vaInt8, vaInt16, vaInt32, vaExtended, vaString, vaIdent, vaFalse, vaTrue, vaBinary, vaSet, vaLString, vaNil, vaCollection };

TValueType __fastcall NextValue(void);

Description

NextValue is used internally by reader methods to query the type of the next item in the stream. After identifying the type of the next item, NextValue returns with the stream position still before the value-type indicator.

The TValueType type defines the kinds of values written to and read from filer objects. C++Builder's filers use a tagged value system, where each value on the stream is preceded by a prefix indicating its type. Those prefixes are of type TValueType.


TReader::Read

TReader	See also

Reads data from the associated stream.

void __fastcall Read(void *Buf, int Count);

Description

Do not call read directly. Read is used internally to read data from the stream. Many other writer methods call Read, usually after setting pertinent values or verifying data types.


TReader::ReadBoolean

TReader	See also

Reads a boolean from the reader object's stream and returns that boolean value.

bool __fastcall ReadBoolean(void);

Description

ReadBoolean is a helper method used by other reader methods to read a tagged boolean value at the current reader Position. ReadBoolean uses ReadValue to check the type for a vaTrue value and returns that result.  Note that ReadBoolean will not verify that the value being read is a boolean, only whether or not the value is true.


TReader::ReadChar

TReader	See also

Reads a character from the reader object's stream and returns that character value.

char __fastcall ReadChar(void);

Description

ReadChar is a helper method used by other reader methods to read a tagged character value at the current reader Position. ReadChar first checks the value type (TValueType) by calling the ReadValue method. If the item is a vaString, ReadString checks the length. If the length indicates that the value is a char, it calls Read and returns the character. Otherwise a EReadError exception is raised.

Note:	If the tagged data is a string with length = 1, it is char compatible. If length > 1, it is an error, however, the rest of the string data must be read to keep the reader in a consistent state. Each action that processes tagged data must leave the reader Position at the start of the next unread tag.


TReader::ReadCollection

TReader

Reads a collection from the reader object's stream and returns that character value.

void __fastcall ReadCollection(TCollection* Collection);

Description

ReadCollection is a helper method used by other reader methods to read a tagged collection value at the current reader Position.  ReadCollection iterates through items in a collection so that each item in a collection property has an opportunity to stream out its properties.  This method does not write out the number of items and the collection indices, because a user can add or delete items.


TReader::ReadComponent

TReader	See also

Reads the component specified by Instance from the stream and returns the component.

TComponent* __fastcall ReadComponent(TComponent* Component);

Description

ReadComponent is called by ReadRootComponent to read each of the components owned by Root. Users would not need to call ReadComponent directly.

ReadComponent handles the loading and initialization process for each component. After loading all the components in the list, ReadComponents calls the Loaded method of each loaded component in the order it read them. ReadComponent manages the complexities of reading the component from the stream through calls to other reader methods and to the component’s methods.


TReader::ReadComponents

TReader

Reads a list of owned components from the reader object's associated stream.

typedef void __fastcall (__closure *TReadComponentsProc)(TComponent* Component);

void __fastcall ReadComponents(TComponent* AOwner, TComponent* AParent, TReadComponentsProc &Proc);

Description

ReadComponents is used internally by the C++Builder environment for design-time streaming. Do not call ReadComponents directly.

ReadComponents first sets the reader object's Root and Owner properties to the component passed in the AOwner parameter and sets its Parent property to AParent. Next ReadComponents reads components by calling the ReadComponent method, passing each returned component to the method passed in Proc.

Note:	ReadComponents is used at design-time for clipboard cut and paste of multiple components.


TReader::ReadFloat

TReader	See also

Reads a floating-point number from the reader object's stream and returns its value.

Extended __fastcall ReadFloat(void);

Description

ReadFloat is a helper method used by other reader methods to read a tagged floating-point data value at the current reader Position. ReadFloat first checks the value type (TValueType) by calling the ReadValue method. If the item is a vaExtended, ReadFloat calls Read and returns the float value. Otherwise it calls ReadInteger.


TReader::ReadIdent

TReader	See also

Reads an identifier from the reader object's stream and returns the identifier.

System::AnsiString __fastcall ReadIdent();

Description

ReadIndent is a helper method used by other reader methods to read an identifying type at the current reader Position. ReadIndent first checks the value type (TValueType) by calling the ReadValue method. If the item is:

•	A vaIdent type, ReadIndent calls Read and returns the identifier string value.

•	A vaFalse type, ReadIdent returns the string ‘false::’

•	A vaTrue type, ReadIdent returns the string ‘true::’

•	A vaNil type, ReadIdent returns the string ‘NULL::’

Otherwise it throws an EReadError exception.


TReader::ReadInteger

TReader	See also

Reads an integer-type number from the reader object's stream and returns its value.

int __fastcall ReadInteger(void);

Description

ReadInteger is a helper method used by other reader methods to read a tagged integer value at the current reader Position. ReadInteger first checks the value type (TValueType) by calling the ReadValue method. If the item is a vaString or a vaInt8, vaInt16 or vaInt32 type , ReadInteger calls Read and returns the integer value. Otherwise it throws an EReadError exception.


TReader::ReadListBegin

TReader	See also

Reads a start-of-list marker from the reader object's associated stream.

void __fastcall ReadListBegin(void);

Description

ReadListBegin is used by other methods that iterate through a list of items to ensure that the type about to be read is a list. ReadListBegin is also used by component writers in defined property ReadData methods.

If the next item in the stream is not a start-of list marker as written by the WriteListBegin method, ReadListBegin throws an EReadError exception.

A call to ReadListBegin is generally followed by a reading loop that terminates when the EndOfList method returns true, indicating that an end-of-list marker is next on the stream, at which point a call to ReadListEnd is required.


TReader::ReadListEnd

TReader	See also

Reads an end-of-list marker from the reader object's associated stream.

void __fastcall ReadListEnd(void);

Description

ReadListEnd is used by other methods that iterate through a list of items to signal the end of a group of items being read. ReadListEnd is also used by component writers in defined property ReadData methods.

A call to ReadListEnd is generally preceded by a reading loop that terminates when the EndOfList method returns true, indicating that an end-of-list marker is next on the stream.

If the item read is not an end-of-list marker, ReadListEnd throws an EReadError exception. A call to ReadListEnd must correspond to a preceding call to ReadListBegin.


TReader::ReadPrefix

TReader	See also

Reads preliminary information concerning form inheritance for a component.

enum TFilerFlag { ffInherited, ffChildPos };

typedef Set<TFilerFlag, ffInherited, ffChildPos> TFilerFlags;

void __fastcall ReadPrefix(TFilerFlags &Flags, int &AChildPos);

Description

ReadPrefix is used internally by the component streaming system. It is called automatically by ReadComponent to read two flags to determine whether a component is a component in an inherited form and whether its creation order in the form is important. It also reads the component’s position in the ancestor form's creation order. When a writer object writes a component to its stream, it prefaces the component with these flags.

The TFilerFlags type is the type of the Flags parameter.


TReader::ReadRootComponent

TReader	See also

Reads a component and all its owned components from the reader object's stream.

TComponent* __fastcall ReadRootComponent(TComponent* Root);

Description

Do not call ReadRootComponent directly. It is used internally by the VCL streaming system. When the reader object is created by its stream in TStream::ReadComponent, it immediately calls the ReadRootComponent method, which initiates the streaming sequence of restoring an object.

ReadRootComponent first calls the ReadSignature method to ensure that it is reading a proper component. ReadRootComponent also handles initializations and fixup references. For example, the component passed in Root becomes the value of the Root property for the reader object.

ReadRootComponent calls the component’s ReadState method, which calls back to TReader::ReadData. TComponent::ReadState is virtual, thus providing an opportunity for the component to prepare itself for being loaded with the new data from the stream.


TReader::ReadSignature

TReader	See also

Reads the filer signature from the reader object's associated stream.

void __fastcall ReadSignature(void);

Description

ReadSignature is used by several routines to ensure that the file about to be read is a valid C++Builder component stream. For example, ReadRootComponent, calls ReadSignature before reading its component from the stream. By checking for the signature before loading objects, the reader object can guard against inadvertently reading invalid or corrupted data.


TReader::ReadStr

TReader	See also

Reads a string value.

System::AnsiString __fastcall ReadStr();

Description

Do not call ReadStr directly. ReadStr is for internal use by certain VCL components.

Warning:	Use ReadString instead for reading component strings to streams. ReadStr can corrupt data if not used correctly.


TReader::ReadString

TReader	See also

Reads a tagged string value written by WriteString from the reader object's stream and returns its contents.

System::AnsiString __fastcall ReadString();

Description

ReadString is a helper method used by other reader methods to read a string at the current reader Position. ReadString first checks the value type (TValueType) by calling the ReadValue method. If the item is a vaString or a vaLString type ReadString calls Read and returns the string. Otherwise it throws an EReadError exception.

Warning:	Always use ReadString for reading component strings to streams. The similarly-named ReadStr method is for internal use only by certain VCL components.


TReader::ReadValue

TReader	See also

Reads the type of the next item on the reader object's stream and returns with the stream positioned after the value-type indicator.

enum TValueType { vaNull, vaList, vaInt8, vaInt16, vaInt32, vaExtended, vaString, vaIdent, vaFalse, vaTrue, vaBinary, vaSet, vaLString, vaNil, vaCollection };

TValueType __fastcall ReadValue(void);

Description

ReadValue is used by other reader methods when the subsequent processing depends upon a type check of the data about to be read.

The TValueType type defines the kinds of values written to and read from filer objects. C++Builder's filers use a tagged value system, where each value on the stream is preceded by a prefix indicating its type. Those prefixes are of type TValueType.


TReader::ReferenceName

TReader 	See also

Generates an OnReferenceName event.

virtual void __fastcall ReferenceName(System::AnsiString &Name);

Description

Do not use the ReferenceName method.  It is used internally.


TReader::SetName

TReader	See also

Allows a reader object to change the names of components being read from the associated stream before assigning them to the Name properties of the components.

virtual void __fastcall SetName(TComponent* Component, System::AnsiString &Name);

Description

SetName is called by ReadComponent. After reading the name, ReadComponent passes the name read from the stream in the Name parameter to SetName. Name is passed by reference, so SetName can change the string before returning.

SetName also calls any event handler attached to the OnSetName event, passing the name string as a by reference parameter, so the attached handler can also modify the string.


TReader::TReader

TReader 	See also

Creates a new TReader object.

__fastcall virtual ~TReader(void);

Description

Do not create reader objects. Readers are automatically created in a stream object’s methods or in global routines that initiate the streaming process. These include:

•	the global routine ObjectBinaryToText procedure, which directly creates a reader object.

•	the global ReadComponentResFile function, which creates a file stream that creates a reader object.

•	the TStream::ReadComponent method, which creates a reader object.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TFiler


TRegistryIniFile

Hierarchy	Properties	Methods	See also

TRegistryIniFile is a low-level wrapper for the Windows 95/NT system registry.

Unit

registry

Description

TRegistryIniFile enables handling the Windows 95/NT system registry as if it were a Windows 3.x INI file. Instead of processing an INI file, however, TRegistryIniFile reads from and writes to the system registry. This enables existing applications that used INI files to use the system registry with a minimum of coding changes.

TRegistryIniFile is derived from TCustomIniFile. It inherits all of the properties and methods of TCustomIniFile, and adds to them the same properties and methods used by the TIniFile object. It also overrides many of the methods inherited from TCustomIniFile to adapt the functionality of the methods to operate on Registry entries, rather than INI file keys. TRegistryIniFile provides essentially the same functionality as TRegIniFile. But because it descends from TCustomIniFile (whereas TRegIniFile descends from TRegistry), it may be used in the same context as other objects that descend from TCustomIniFile where TRegIniFile cannot. It may be passed as a parameter compatible with type TCustomIniFile, just as is the case with TIniFile or TMemIniFile.

TRegistryIniFile is particularly useful for migrating a 16-bit Windows 3.x application to Windows 95/NT. By finding all references to TIniFile in an application’s source code, replacing them with TRegistryIniFile, and recompiling the application, a developer can update an application to use the system registry instead of INI files without having to code any new logic into the application.

Note:	Information contained in existing users’ INI files is not migrated into the system registry using the method described above. A one-time operation to explicitly copy the INI file data, through TRegistryIniFile, must be used to do this.

Tip:	TRegistryIniFile presents a simple interface to the system registry and hides the need to know about the underlying structure of the registry. Some developers may prefer to use TRegistryIniFile instead of TRegistry in their applications.


TRegistryIniFile properties

TRegistryIniFile	Alphabetically	Legend

Derived from TCustomIniFile

FileName


TRegistryIniFile properties

TRegistryIniFile	By object	Legend

FileName


TRegistryIniFile::RegIniFile

TRegistryIniFile	See also

Contains and internal instance of a TRegIniFile object.

__property TRegIniFile* RegIniFile = {read=FRegIniFile};

Description

RegIniFile is used internally by the TRegistryIniFile object as the gateway connection between TRegistryIniFile methods the the system registry.


TRegistryIniFile methods

TRegistryIniFile	Alphabetically

In TRegistryIniFile

~TRegistryIniFile

DeleteKey

EraseSection

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

TRegistryIniFile

UpdateFile

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime

Derived from TCustomIniFile

ReadBool

SectionExists

ValueExists

WriteBool

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRegistryIniFile methods

TRegistryIniFile	By object

~TRegistryIniFile

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DeleteKey

Dispatch

EraseSection

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadBool

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

SectionExists

TRegistryIniFile

UpdateFile

ValueExists

WriteBool

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime


TRegistryIniFile::TRegistryIniFile

TRegistryIniFile	See also

Creates a TRegistryIniFile object for an application.

__fastcall TRegistryIniFile(const System::AnsiString FileName);

Description

Call TRegistryIniFile to construct a TRegistryIniFile object for an application. TRegistryIniFile inherits TRegistryIniFile from TObject, and creates an additional property, RegIniFile, which an internal TRegIniFile object used to access the system registry.

FileName is used as the FileName property for the internal TRegIniFile object in the RegIniFile property.


TRegistryIniFile::DeleteKey

TRegistryIniFile	See also 	Example

Erases the data value associated with an INI file entry.

virtual void __fastcall DeleteKey(const System::AnsiString Section, const System::AnsiString Ident);

Description

Call DeleteKey to erase a data value associated with an INI file entry. Section is string containing the name of an INI file section, and Ident is a string containing the name of the key from for which to set a NULL value.

Note:	Attempting to erase a data value in a non-existent section or attempting to erase data from a non-existent key are not errors. In these cases, DeleteKey creates the section and key and sets its initial value to an empty value.


TRegistryIniFile::EraseSection

TRegistryIniFile	See also

Erases an entire section of an INI file.

virtual void __fastcall EraseSection(const System::AnsiString Section);

Description

Call EraseSection to remove a section, all its keys, and their data values from an INI file. Section identifies the INI file section to remove. If a section cannot be removed, an exception is raised.


TRegistryIniFile::ReadDate
 KTRegistryIniFile::ReadDate

TRegistryIniFile	See also

Retrieves a date value from an INI file.

virtual System::TDateTime __fastcall ReadDate(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Default);

Description

Call ReadDate to read a date value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the date value. Default is the date value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TRegistryIniFile::ReadDateTime

TRegistryIniFile	See also

Retrieves a date-time value from an INI file.

virtual System::TDateTime __fastcall ReadDateTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Default);

Description

Call ReadDateTime to read a date-time value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the date-time value. Default is the date-time value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TRegistryIniFile::ReadFloat

TRegistryIniFile	See also

Retrieves a float value from an INI file.

virtual double __fastcall ReadFloat(const System::AnsiString Section, const System::AnsiString Name, double Default);

Description

Call ReadFloat to read a float value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the float value. Default is the float value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TRegistryIniFile::ReadInteger

TRegistryIniFile	See also 	Example

Retrieves an integer value from an INI file.

virtual int __fastcall ReadInteger(const System::AnsiString Section, const System::AnsiString Ident, int Default);

Description

Call ReadInteger to read an integer value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the value. Default is the integer value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TRegistryIniFile::ReadSection

TRegistryIniFile	See also

Reads all the key names from a specified section of an INI file into a string list.

virtual void __fastcall ReadSection(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSection to retrieve the names of all keys within a specified section of an INI file into a string list object.

Section identifies the section from which to retrieve a list of key names. Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object such as a string list, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TRegistryIniFile::ReadSections

TRegistryIniFile	See also

Reads the names of all sections in an INI file into a string list.

virtual void __fastcall ReadSections(Classes::TStrings* Strings);

Description

Call ReadSections to retrieve the names of all sections in an INI file into a string list object.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TRegistryIniFile::ReadSectionValues

TRegistryIniFile	See also	Example

Reads the values from all keys within a section of an INI file into a string list.

virtual void __fastcall ReadSectionValues(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSectionValues to read the values from all keys within a specified section of an INI file into a string list object. Section identifies the section in the file from which to read key values. Strings is the string list object into which to read the values.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TRegistryIniFile::ReadString

TRegistryIniFile	See also 	Example

Retrieves a string value from an INI file.

virtual System::AnsiString __fastcall ReadString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Default);

Description

Call ReadString to read a string value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the value. Default is the string value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TRegistryIniFile::ReadTime

TRegistryIniFile	See also

Retrieves a time value from an INI file.

virtual System::TDateTime __fastcall ReadTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Default);

Description

Call ReadTime to read a time value from an INI file. Section identifies the section in the file that contains the desired key. Ident is the name of the key from which to retrieve the time value. Default is the time value to return if the:

•	Section does not exist.

•	Key does not exist.

•	Data value for the key is not assigned.


TRegistryIniFile::UpdateFile
TRegistryIniFile. UpdateFile

TRegistryIniFile	See also

Flushes buffered INI file data to disk.

virtual void __fastcall UpdateFile(void);

Description

Call UpdateFile to flush buffered reads from and writes to the INI file to disk. UpdateFile is useful under Windows95, but has no effect under Windows NT as NT does not buffer INI file reads and writes.


TRegistryIniFile::WriteDate

TRegistryIniFile	See also

Writes a date value to an INI file.

virtual void __fastcall WriteDate(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteDate to write a date value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the date value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteDate creates the section and key and sets its initial value to Value.


TRegistryIniFile::WriteDateTime

TRegistryIniFile	See also

Writes a date-time value to an INI file.

virtual void __fastcall WriteDateTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteDateTime to write a date-time value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the date-time value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteDateTime creates the section and key and sets its initial value to Value.


TRegistryIniFile::WriteFloat

TRegistryIniFile	See also

Writes a float value to an INI file.

virtual void __fastcall WriteFloat(const System::AnsiString Section, const System::AnsiString Name, double Value);

Description

Call WriteFloat to write a float value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the float value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteFloat creates the section and key and sets its initial value to Value.


TRegistryIniFile::WriteInteger

TRegistryIniFile	See also 	Example

Writes an integer value to an INI file.

virtual void __fastcall WriteInteger(const System::AnsiString Section, const System::AnsiString Ident, int Value);

Description

Call WriteInteger to write an integer value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the integer value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteInteger creates the section and key and sets its initial value to Value.


TRegistryIniFile::WriteString

TRegistryIniFile	See also 	Example

Writes a string value to an INI file.

virtual void __fastcall WriteString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Value);

Description

Call WriteString to write a string value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the string value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteString creates the section and key and sets its initial value to Value.


TRegistryIniFile::WriteTime

TRegistryIniFile	See also

Writes a time value to an INI file.

virtual void __fastcall WriteTime(const System::AnsiString Section, const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteTime to write a time value to an INI file. Section identifies the section in the file that contain the key to which to write. Ident is the name of the key for which to set a value. Value is the time value to write.

Note:	Attempting to write a data value to a non-existent section or attempting to write data to a non-existent key are not errors. In these cases, WriteTime creates the section and key and sets its initial value to Value.


TRegistryIniFile::~TRegistryIniFile

TRegistryIniFile

~TRegistryIniFile frees the memory associated with the TRegistryIniFile object.

__fastcall virtual ~TRegistryIniFile(void);

Description

Do not call ~TRegistryIniFile directly. Instead, use the delete keyword on the object, which causes ~TRegistryIniFile to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TCustomIniFile


TRegIniFile

Hierarchy	Properties	Methods 	See also

TRegIniFile is a low-level wrapper for the Windows 95/NT system registry.

Unit

registry

Description

TRegIniFile enables handling the Windows 95/NT system registry as if it were a Windows 3.x INI file. Instead of processing an INI file, however, TRegIniFile reads from and writes to the system registry. This enables existing applications that used INI files to use the system registry with a minimum of coding changes.

TRegIniFile is derived from TRegistry. It inherits all of the properties and methods of TRegistry, and adds to them the same properties and methods used by the TIniFile object. Some of the added methods for TRegIniFile, such as ReadBool and WriteBool, override the methods of TRegistry.

The FileName passed to a TRegIniFile object becomes a subkey under the system registry’s root key (HKEY_CURRENT_USER by default). What corresponds to a section in an INI file is treated as a key in the system registry, and what corresponds to data entries under a section in an INI file are treated as data values under a key in the system registry.

TRegIniFile is particularly useful for migrating a 16-bit Windows 3.x application to Windows 95/NT. By finding all references to TIniFile in an application’s source code, replacing them with TRegIniFile, and recompiling the application, a developer can update an application to use the system registry instead of INI files without having to code any new logic into the application.

Note:	Information contained in existing users’ INI files is not migrated into the system registry using the method described above.

Tip:	TRegIniFile presents a simple interface to the system registry and hides the need to know about the underlying structure of the registry. Some developers may prefer to use TRegIniFile instead of TRegistry in their applications.


TRegIniFile properties

TRegIniFile	Alphabetically	Legend

In TRegIniFile

FileName

Derived from TRegistry

CurrentKey

CurrentPath

LazyWrite

RootKey


TRegIniFile properties

TRegIniFile	By object	Legend

CurrentKey

CurrentPath

FileName

LazyWrite

RootKey


TRegIniFile::FileName

TRegIniFile	See also

Specifies the name of the key opened or created in the system registry.

__property System::AnsiString FileName = {read=FFileName};

Description

Query FileName to determine the name of the key in the system registry that is the root key for all TRegIniFile operations.


TRegIniFile methods

TRegIniFile	Alphabetically

In TRegIniFile

~TRegIniFile

DeleteKey

EraseSection

ReadBool

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

TRegIniFile

WriteBool

WriteInteger

WriteString

Derived from TRegistry

CloseKey

CreateKey

DeleteValue

GetDataInfo

GetDataSize

GetDataType

GetKeyInfo

GetKeyNames

GetValueNames

HasSubKeys

KeyExists

LoadKey

MoveKey

OpenKey

ReadBinaryData

ReadCurrency

ReadDate

ReadDateTime

ReadFloat

ReadTime

RegistryConnect

RenameValue

ReplaceKey

RestoreKey

SaveKey

UnLoadKey

ValueExists

WriteBinaryData

WriteCurrency

WriteDate

WriteDateTime

WriteFloat

WriteTime

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRegIniFile methods

TRegIniFile	By object

~TRegIniFile

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CloseKey

CreateKey

DefaultHandler

DeleteKey

DeleteValue

Dispatch

EraseSection

FieldAddress

Free

FreeInstance

GetDataInfo

GetDataSize

GetDataType

GetKeyInfo

GetKeyNames

GetValueNames

HasSubKeys

InheritsFrom

InitInstance

InstanceSize

KeyExists

LoadKey

MethodAddress

MethodName

MoveKey

NewInstance

OpenKey

ReadBinaryData

ReadBool

ReadCurrency

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadSection

ReadSections

ReadSectionValues

ReadString

ReadTime

RegistryConnect

RenameValue

ReplaceKey

RestoreKey

SaveKey

TRegIniFile

UnLoadKey

ValueExists

WriteBinaryData

WriteBool

WriteCurrency

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime


TRegIniFile::TRegIniFile

TRegIniFile	See also

Creates a TRegIniFile object for an application.

__fastcall TRegIniFile(const System::AnsiString FileName);

Description

Call TRegIniFile to construct a TRegIniFile object for an application. TRegIniFile inherits TRegIniFile from TRegistry, and creates an additional property, FileName, which is used to specify the name of the key to open or create in the registry.


TRegIniFile::DeleteKey

TRegIniFile	See also

Erases a data value that is associated with a key.

HIDESBASE void __fastcall DeleteKey(const System::AnsiString Section, const System::AnsiString Ident);

Description

Call DeleteKey to erase a data value associated with a key. Section is string containing the name of the system registry key containing the value to delete. Ident is a string containing the name of the data value to delete.

Note:	DeleteKey for TRegIniFile overrides the DeleteKey method of TRegistry, from which TRegIniFile descends. You can access TRegistry's DeleteKey method by casting the call to DeleteKey as type TRegistry.

Note:	On Windows 95, DeleteKey will delete the key and all its subkeys. On Windows NT, the subkeys must be explicitly deleted by separate calls to DeleteKey.


TRegIniFile::EraseSection

TRegIniFile	See also

Deletes a key and its data values in the system registry.

void __fastcall EraseSection(const System::AnsiString Section);

Description

Call EraseSection to remove a key and its data values from the system registry. Section identifies the key to delete.


TRegIniFile::ReadBool

TRegIniFile	See also

Retrieves a Boolean value from a specified data value associated with a key.

HIDESBASE bool __fastcall ReadBool(const System::AnsiString Section, const System::AnsiString Ident, bool Default);

Description

Call ReadBool to retrieve a Boolean value from a specified data value associated with a key.

Section is a string that identifies the key from which to retrieve a data value. Ident is a string that identifies the name of the data value to return. Default is a Boolean value to use if there is no key corresponding to Section or no data value corresponding to Ident.

Note:	This function overrides the ReadBool function of TRegistry, from which TRegIniFile is derived. To call the ReadBool function of TRegistry instead of this function, cast the call to ReadBool as TRegistry.


TRegIniFile::ReadInteger

TRegIniFile	See also

Retrieves an integer value from a specified data value (Ident) associated with a key (Section).

HIDESBASE int __fastcall ReadInteger(const System::AnsiString Section, const System::AnsiString Ident, int Default);

Description

Call ReadInteger to retrieve an integer value from a specified data value associated with a key.

Section is a string that identifies the key from which to retrieve a data value. Ident is a string that identifies the name of the data value to return. Default is an integer value to use if there is no key corresponding to Section or no data value corresponding to Ident.

Note:	This function overrides the ReadInteger function of TRegistry, from which TRegIniFile is derived. To call the ReadInteger function of TRegistry instead of this function, cast the call to ReadInteger as TRegistry.


TRegIniFile::ReadSection

TRegIniFile	See also

Retrieves the names of all data values associated with a key, and stores the names in a TStrings object.

void __fastcall ReadSection(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSection to retrieve the names of all data values associated with a key into a TStrings object. Section is a string identifying the key for which to retrieve data-value names.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object such as a string list, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TRegIniFile::ReadSections

TRegIniFile	See also

Retrieves the names of all subkeys associated with the current key.

void __fastcall ReadSections(Classes::TStrings* Strings);

Description

Call ReadSections to retrieve the names of all subkeys associated with the current key.

Strings specifies the string object to hold the retrieved names. Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself.


TRegIniFile::ReadSectionValues

TRegIniFile	See also

Retrieves the data-values associated with a specified key, and stores the retrieved values in a string object.

void __fastcall ReadSectionValues(const System::AnsiString Section, Classes::TStrings* Strings);

Description

Call ReadSectionValues to read all data values associated with a specified key into a string object. Section is the name of the key from which to retrieve data-values. Strings specifies the string object to hold the retrieved values.

Strings can point to a TStrings object, or to a component property, such as Items for a TListBox component, that is a TStrings object itself. Use the Values property of the string object to access a specific string in the object.


TRegIniFile::ReadString

TRegIniFile	See also

Retrieves a string value from a specified data value (Ident) associated with a key (Section).

HIDESBASE System::AnsiString __fastcall ReadString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Default);

Description

Call ReadString to retrieve a string value from a specified data value associated with a key.

Section is a string that identifies the key from which to retrieve a data value. Ident is a string that identifies the name of the data value to return. Default is a string value to use if there is no key corresponding to Section or no data value corresponding to Ident.

Note:	This function overrides the ReadString function of TRegistry, from which TRegIniFile is derived. To call the ReadString function of TRegistry instead of this function, cast the call to ReadString as TRegistry.


TRegIniFile::WriteBool

TRegIniFile	See also

Writes a Boolean value to a specified data value associated with a specified key.

HIDESBASE void __fastcall WriteBool(const System::AnsiString Section, const System::AnsiString Ident, bool Value);

Description

Call WriteBool to store a Boolean value in a data value associated with a specified key.

Section is a string identifying the key into which to store a data value. Ident is a string identifying the name of the data value into which to write. Value is the Boolean value to write into the data value.

Note:	This function overrides the WriteBool procedure of TRegistry, from which TRegIniFile is derived. To call the WriteBool procedure of TRegistry instead of this procedure, cast the call to WriteBool as TRegistry.


TRegIniFile::WriteInteger

TRegIniFile	See also

Writes a long integer value to a specified data value associated with a specified key.

HIDESBASE void __fastcall WriteInteger(const System::AnsiString Section, const System::AnsiString Ident, int Value);

Description

Call WriteInteger to store an integer value in a data value associated with a specified key.

Section is a string identifying the key into which to store a data value. Ident is a string identifying the name of the data value into which to write. Value is the integer value to write into the data value.

Note:	This function overrides the WriteInteger procedure of TRegistry, from which TRegIniFile is derived. To call the WriteInteger procedure of TRegistry instead of this procedure, cast the call to WriteInteger as TRegistry.


TRegIniFile::WriteString

TRegIniFile	See also

Writes a string value to a specified data value associated with a specified key.

HIDESBASE void __fastcall WriteString(const System::AnsiString Section, const System::AnsiString Ident, const System::AnsiString Value);

Description

Call WriteString to store a string value in a data value associated with a specified key.

Section is a string identifying the key into which to store a data value. Ident is a string identifying the name of the data value into which to write. Value is the string value to write into the data value.

Note:	This function overrides the WriteString procedure of TRegistry, from which TRegIniFile is derived. To call the WriteString procedure of TRegistry instead of this procedure, cast the call to WriteString as TRegistry.


TRegIniFile::~TRegIniFile

TRegIniFile

~TRegIniFile frees the memory associated with the TRegIniFile object.

__fastcall virtual ~TRegIniFile(void) { }

Description

Do not call ~TRegIniFile directly. Instead, use the delete keyword on the object, which causes ~TRegIniFile to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TRegistry


TRegistry

Hierarchy	Properties	Methods

TRegistry is a low-level wrapper for the MicrosoftWindows95/NT system registry and functions that operate on the registry.

Unit

registry

Description

Use TRegistry to encapsulate access to the Windows 95/NT system registry in an application. The registry is a database that an applications can use to store and retrieve configuration information. Configuration information is stored in a hierarchical tree. Each node in the tree is called a key. Every key can contain subkeys and data values that represent part of the configuration information for an application.

All keys that an application creates, opens, reads, or writes are subkeys of  predefined root keys. By default, a TRegistry object is created with a root key of HKEY_CURRENT_USER.

Only one key is accessible at a time in a TRegistry object. To determine the key that is currently accessible, read the value of the CurrentKey property. TRegistry methods enable an application to open, close, save, move, copy, and delete keys.

One or more data values containing actual configuration information can be stored in a key. TRegistry methods enable an application to query a key to see if it contains data, to read data in a key, and to write data to a key.


TRegistry properties

TRegistry	Alphabetically	Legend

In TRegistry

CurrentKey

CurrentPath

LazyWrite

RootKey


TRegistry properties

TRegistry	By object	Legend

CurrentKey

CurrentPath

LazyWrite

RootKey


TRegistry::CurrentKey

TRegistry	See also

Specifies the registry key that is currently open.

__property HKEY CurrentKey = {read=FCurrentKey, nodefault};

Description

Use CurrentKey to determine the registry key that is currently open. All operations performed by TRegistry affect only the current key. To access another key, call the OpenKey method.


TRegistry::CurrentPath

TRegistry	See also

Indicates the registry path associated with the current key.

__property System::AnsiString CurrentPath = {read=FCurrentPath};

Description

Use CurrentPath to determine the registry path of the current key. The system registry is hierarchical, and CurrentPath returns a string that spells out the hierarchy of keys from the root key to the current key, inclusive.

CurrentPath is automatically reset each time a different key becomes the current key.


TRegistry::LazyWrite

TRegistry	See also

Specifies how keys are written to the registry when calling the CloseKey procedure.

__property bool LazyWrite = {read=FLazyWrite, write=FLazyWrite, nodefault};

Description

Use LazyWrite to specify how keys are written to the registry. LazyWrite is initialized to true when a registry object is first created. When LazyWrite is true, keys are written to the registry when they are closed, but the CloseKey procedure may return before the write operation takes place.

When LazyWrite is false, keys are written to the registry before CloseKey returns. Set LazyWrite to false only when absolutely necessary. Setting LazyWrite to false guarantees that the changes an application makes to keys are written to the registry before further application processing takes place, but it uses more system resources when keys are closed. If LazyWrite is false, and an application is displaying or changing many registry entries, there will be a degradation to application performance.


TRegistry::RootKey

TRegistry	See also

Specifies the root key for the TRegistry object in an application.

__property HKEY RootKey = {read=FRootKey, write=SetRootKey, nodefault};

Description

Use RootKey to determine the hierarchy of subkeys an application can access, or to specify the root key for the application.

By default, RootKey is set to HKEY_CURRENT_USER when the registry object is created. To change the root key, specify a valid integer value for the RootKey property.

Note:	For some operations, such as LoadKey or RegistryConnect, an application may need to change the default value of RootKey.


TRegistry methods

TRegistry	Alphabetically

In TRegistry

~TRegistry

CloseKey

CreateKey

DeleteKey

DeleteValue

GetDataInfo

GetDataSize

GetDataType

GetKeyInfo

GetKeyNames

GetValueNames

HasSubKeys

KeyExists

LoadKey

MoveKey

OpenKey

ReadBinaryData

ReadBool

ReadCurrency

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadString

ReadTime

RegistryConnect

RenameValue

ReplaceKey

RestoreKey

SaveKey

TRegistry

UnLoadKey

ValueExists

WriteBinaryData

WriteBool

WriteCurrency

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRegistry methods

TRegistry	By object

~TRegistry

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CloseKey

CreateKey

DefaultHandler

DeleteKey

DeleteValue

Dispatch

FieldAddress

Free

FreeInstance

GetDataInfo

GetDataSize

GetDataType

GetKeyInfo

GetKeyNames

GetValueNames

HasSubKeys

InheritsFrom

InitInstance

InstanceSize

KeyExists

LoadKey

MethodAddress

MethodName

MoveKey

NewInstance

OpenKey

ReadBinaryData

ReadBool

ReadCurrency

ReadDate

ReadDateTime

ReadFloat

ReadInteger

ReadString

ReadTime

RegistryConnect

RenameValue

ReplaceKey

RestoreKey

SaveKey

TRegistry

UnLoadKey

ValueExists

WriteBinaryData

WriteBool

WriteCurrency

WriteDate

WriteDateTime

WriteFloat

WriteInteger

WriteString

WriteTime


TRegistry::CloseKey

TRegistry	See also

Writes the current key to the registry and closes the key.

void __fastcall CloseKey(void);

Description

Call CloseKey to write the current key to the registry and close the key. An application should not keep keys open any longer than necessary. Many TRegistry methods routinely call CloseKey after reading from or writing to the registry. Calling CloseKey when there is no current key has no effect.

Note:	When an application closes a key, the key is written to the registry. The LazyWrite property determines how the write takes place.


TRegistry::TRegistry

TRegistry	See also

Creates a TRegistry object for an application.

__fastcall TRegistry(void);

Description

Call TRegistry to instantiate a TRegistry object for an application. TRegistry sets the RootKey property of TRegistry to HKEY_CURRENT_USER, and sets the LazyWrite property to true.


TRegistry::TRegistry
TRegistry::CreateKey

TRegistry	See also

Creates a new key in the registry.

bool __fastcall CreateKey(const System::AnsiString Key);

Description

Use CreateKey to add a new key to the registry. Key is the name of the key to create. Key can be an absolute or relative name. An absolute key begins with a backslash (\) and is a subkey of the root key. A relative key is a subkey of the current key.

CreateKey returns true if key creation is successful. On error, an exception is raised, and CreateKey returns false. Attempting to create a key that already exists has no effect.

CreateKey creates only non-volatile keys. If you need to create volatile keys on Windows NT, you must call the Windows API directly.

CreateKey creates keys with a security access of KEY_ALL_ACCESS. If you need to create keys with more restricted access, you must call the Windows API directly.

A key created by CreateKey has no values. To set key values, use the WriteCurrency, WriteBinaryData, WriteBool, WriteDate, WriteDateTime, WriteFloat, WriteInteger, WriteString, or WriteTime procedures.


TRegistry::DeleteKey

TRegistry	See also

Removes a specified key and its associated data from the registry.

bool __fastcall DeleteKey(const System::AnsiString Key);

Description

Call DeleteKey to remove a specified key and its associated data, if any, from the registry. Under Windows 95, if the key has subkeys, the subkeys and any associated data are also removed. Under Windows NT, subkeys must be explicitly deleted by separate calls to DeleteKey.

DeleteKey returns true if key deletion is successful. On error, DeleteKey returns false.


TRegistry::DeleteValue

TRegistry	See also

Erases a data value that is associated with the current key.

bool __fastcall DeleteValue(const System::AnsiString Name);

Description

Call DeleteValue to remove a specific data value associated with the current key. Name is string containing the name of the value to delete. Keys can contain multiple data values, and every value associated with a key has a unique name.

DeleteValue returns true if the deletion is successful, false if the deletion fails.


TRegistry::~TRegistry

TRegistry	See also

Closes the current key and destroys the TRegistry object.

__fastcall virtual ~TRegistry(void);

Description

~TRegistry closes the current key and frees the resources allocated for a registry object when it is no longer needed.


TRegistry::GetDataInfo

TRegistry	See also

Returns information about a specified data value associated with the current key.

bool __fastcall GetDataInfo(const System::AnsiString ValueName, TRegDataInfo &Value);

Description

Call GetDataInfo to get information about a data value associated with the current key. ValueName is a string containing the name of the data value to query. Value is a record of type TRegDataInfo in which information about the data value is returned. If the data value is of type rdString or rdExpandString, the size of the data value includes an extra byte for the terminating null character.

GetDataInfo returns true if data value information is returned. If GetDataInfo fails, it returns false, and the Value record is filled with zeros.

Value is a record of type TRegDataInfo that is declared in an application. Records of type TRegDataInfo contain two fields: a field called RegData, of type TRegDataType, that specifies the data type of the data value; and a field called DataSize that specifies the size, in bytes, of the data value. RegData can have the following values:

Value	Meaning

rdUnknown	Data value type is of no defined value type.

rdString	Data value type is a null-terminated string. It is a Unicode or ANSI string depending on whether the application calls the Unicode or ANSI string functions.

rdExpandString	Data value type is a null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It is a Unicode or ANSI string depending on whether the application calls the Unicode or ANSI string functions.

rdInteger	Data value type is a32-bit number.

rdBinary	Data value type is binary data, in any form.


TRegistry::GetDataSize

TRegistry	See also

Returns the size, in bytes, of a specified data value associated with the current key.

int __fastcall GetDataSize(const System::AnsiString ValueName);

Description

Call GetDataSize to determine the size, in bytes, of a data value associated with the current key. ValueName is a string containing the name of the data value to query.

On success, GetDataSize returns the size of the data value. On failure, GetDataSize returns -1.

Note:	If the data value is a string, GetDataSize returns the size of the data value and one extra byte for the terminating null character.


TRegistry::GetDataType

TRegistry	See also

Returns the enumerated data type of a specified data value associated with the current key.

TRegDataType __fastcall GetDataType(const System::AnsiString ValueName);

Description

Call GetDataType to determine the data type of a data value associated with the current key. ValueName is a string containing the name of the data value to query.

GetDataType returns an enumerated value of type TRegDataType. TRegDataType can be one of the following values

Value	Meaning

rdUnknown	Data value type is of no defined value type.

rdString	Data value type is a null-terminated string. It is a Unicode or ANSI string depending on whether the application calls the Unicode or ANSI string functions.

rdExpandString	Data value type is a null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It is a Unicode or ANSI string depending on whether the application calls the Unicode or ANSI string functions.

rdInteger	Data value type is a32-bit number.

rdBinary	Data value type is binary data, in any form.


TRegistry::GetKeyInfo

TRegistry	See also

Returns information about the current key.

bool __fastcall GetKeyInfo(TRegKeyInfo &Value);

Description

Call GetKeyInfo to return all information about the current key to an application. Value is a variable declared in an application to store the key information returned by this function. Value must be of type TRegKeyInfo. Information returned by GetKeyInfo about the current key includes:

•	Number of subkeys

•	Longest subkey name length, in characters

•	Number of data values

•	Longest data-value name length

•	Longest data-value length

•	Time of last write to the key

On success GetKeyInfo returns true. On failure it returns false, and the Value record is set to zeroes.


TRegistry::GetKeyNames

TRegistry	See also

Returns a string list containing the names of all subkeys belonging to the current key.

void __fastcall GetKeyNames(Classes::TStrings* Strings);

Description

Call GetKeyNames to determine the names of all subkeys belonging to the current key. Determining the names of subkeys is useful in an application that iterates through a set of keys.

Strings is a variable of type TStrings into which to return the list of subkey names.


TRegistry::GetValueNames

TRegistry	See also

Returns a string list containing the names of all data values associated with the current key.

void __fastcall GetValueNames(Classes::TStrings* Strings);

Description

Call GetValueNames to determine the names of all data values associated with the current key. Determining the names of data values is useful in an application that iterates through a set of data values for a key.

Strings is a variable of type TStrings into which to return the list of data value names.


TRegistry::HasSubKeys

TRegistry	See also

Determines if the current key has subkeys.

bool __fastcall HasSubKeys(void);

Description

Call HasSubKeys to determine if the current key has any subkeys. HasSubKeys returns true if the current key has at least one subkey. Otherwise it returns false.


TRegistry::KeyExists

TRegistry	See also

Determines if a specified key exists.

bool __fastcall KeyExists(const System::AnsiString Key);

Description

Call KeyExists to determine if a key of a specified name exists. Key is the name of the key for which to search.


TRegistry::LoadKey

TRegistry	See also

Creates a subkey under the root key and loads registry information from a file into the newly created subkey.

bool __fastcall LoadKey(const System::AnsiString Key, const System::AnsiString FileName);

Description

Call LoadKey to:

1	Create a new subkey under the root key, and

2	Load registry information from a file into the subkey. Registry information can include data values, subkeys, and data values for those subkeys.

LoadKey is intended to simplify creation of a key, its values and subkeys, and the values for those subkeys in a single operation. A key, its subkeys, and all data values the key and its subkeys is called a hive. Rather than creating each key and value separately, an application can read a hive from a file. This is especially useful for applications that users can reconfigure at run time.

Note:	Before an application calls LoadKey the RootKey property must be set to HKEY_USERS, HKEY_LOCAL_MACHINE, or to a key returned by a previous call to RegistryConnect.

The Key parameter is the name of the subkey to create. The FileName parameter is the location of the file containing registry information to store in the subkey. The file specified by FileName must be one previously created using the SaveKey function or the RegSaveKey Windows API function. On systems that use a file allocation table (FAT), FileName cannot include an extension.


TRegistry::MoveKey

TRegistry	See also

Moves an existing key, its subkeys, and data values to a new location using a new key name.

void __fastcall MoveKey(const System::AnsiString OldName, const System::AnsiString NewName, bool Delete);

Description

Call MoveKey to copy or move an existing key, its subkeys, and data values to a different location. Under Windows 95, copying is recursive. If a key contains subkeys and data values, they too, are copied. When the operation is complete, the new key is closed.  Under Windows NT, subkeys must be moved explicitly with separate calls to MoveKey.

OldName specifies the key to copy or move. NewName specifies a name for the duplicate key to create. If the key specified by NewName does not exist, MoveKey creates it. Delete specifies whether to delete the old key after the copy operation. If Delete is true, the key specified by OldName is deleted after it is copied. Otherwise the old key is closed.


TRegistry::OpenKey

TRegistry	See also

Opens a specified key.

bool __fastcall OpenKey(const System::AnsiString Key, bool CanCreate);

Description

Call OpenKey to make a specified key the current key. Key is the name of the key to open. If Key is null, the CurrentKey property is set to the key specified by the RootKey property.

CanCreate specifies whether to create the specified key if it does not exist. If CanCreate is true, the key is created if necessary.

Key is opened or created with the security access value KEY_ALL_ACCESS. OpenKey only creates non-volatile keys, A non-volatile key is stored in the registry and is preserved when the system is restarted.

OpenKey returns true if the key is successfully opened or created


TRegistry::ReadBinaryData

TRegistry	See also

Retrieves a binary value from a specified data value associated with the current key.

int __fastcall ReadBinaryData(const System::AnsiString Name, void *Buffer, int BufSize);

Description

Call ReadBinaryData to read a binary value from a specified data value associated with the current key. Name is the name of the data value to read. Buffer is the application variable into which to read the registry data. Buffer must be large enough to hold all of the data returned. BufSize specifies the size of Buffer.

If successful, ReadBinaryData returns the requested data. On error, an exception is raised, and the value returned by this function should be discarded.

Note:	Binary data is typically an Object Pascal record. It might also be an icon or a bitmap although Microsoft recommends against storing graphics objects in the registry for performance reasons.


TRegistry::ReadBool

TRegistry	See also

Retrieves a Boolean value from a specified data value associated with the current key.

bool __fastcall ReadBool(const System::AnsiString Name);

Description

Call ReadBool to read a Boolean value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadBool returns the requested Boolean value. On error, an exception is raised, and the value returned by this function should be discarded.


TRegistry::ReadCurrency

TRegistry	See also

Retrieves a currency value from a specified data value associated with the current key.

System::Currency __fastcall ReadCurrency(const System::AnsiString Name);

Description

Call ReadCurrency to read a Currency value from a specified data value associated with the current key. Name is the name of the data vale to read.

If successful, ReadCurrency returns a Currency value. On error, an exception is raised, and the value returned by this function should be discarded.


TRegistry::ReadDate

TRegistry	See also

Retrieves a date value from a specified data value associated with the current key.

System::TDateTime __fastcall ReadDate(const System::AnsiString Name);

Description

Call ReadDate to read a date value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadDate returns a C++Builder TDateTime value. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is the time of day.

On error, an exception is raised, and the value returned by this function should be discarded.

Note:	Only use ReadDate to read data values previously stored with the WriteDate procedure.


TRegistry::ReadDateTime

TRegistry	See also

Retrieves a date and time value from a specified data value associated with the current key.

System::TDateTime __fastcall ReadDateTime(const System::AnsiString Name);

Description

Call ReadDateTime to read a datetime value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadDateTime returns a C++Builder TDateTime value. The integral part of a TDateTime value is the number of days that have passed since12/30/1899. The fractional part of a TDateTime value is the time of day.

On error, an exception is raised, and the value returned by this function should be discarded.


TRegistry::ReadFloat

TRegistry	See also

Retrieves a float value from a specified data value associated with the current key.

double __fastcall ReadFloat(const System::AnsiString Name);

Description

Call ReadFloat to read a float value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadFloat returns an Object Pascal Double value. On error, an exception is raised, and the value returned by this function should be discarded.


TRegistry::ReadInteger

TRegistry	See also

Retrieves an integer value from a specified data value associated with the current key.

int __fastcall ReadInteger(const System::AnsiString Name);

Description

Call ReadInteger to read an integer value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadInteger returns an Object Pascal Integer value. On error, an exception is raised, and the value returned by this function should be discarded.


TRegistry::ReadString

TRegistry	See also

Retrieves a string value from a specified data value associated with the current key.

System::AnsiString __fastcall ReadString(const System::AnsiString Name);

Description

Call ReadString to read a string value from a specified data value associated with the current key. Name is the name of the data value to read.

On failure, ReadString returns NULL.


TRegistry::ReadTime

TRegistry	See also

Retrieves a time value from a specified data value associated with the current key.

System::TDateTime __fastcall ReadTime(const System::AnsiString Name);

Description

Call ReadTime to read a time value from a specified data value associated with the current key. Name is the name of the data value to read.

If successful, ReadTime returns a C++Builder TDateTime value. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is the time of day.

On error, an exception is raised, and the value returned by this function should be discarded.

Note:	Only use ReadTime to read data values previously stored with the WriteTime procedure.


TRegistry::RegistryConnect

TRegistry	See also

Establishes a connection to a registry on another computer.

bool __fastcall RegistryConnect(const System::AnsiString UNCName);

Description

Call RegistryConnect to establish a connection to a registry on another computer running Windows 95 or Windows NT. UNCName is the name of the remote computer, and must take the following form:

where computername is the name of the remote computer. If UNCName is NULL, the local machine name is used.

Note:	Before calling RegistryConnect, an application must set the RootKey property for its registry object to HKEY_USERS or HKEY_LOCAL_MACHINE.

If connection is successful, RegistryConnect sets the RootKey property to the root key of the remote computer and returns true. If unsuccessful, RegistryConnect returns false, and RootKey remains unchanged.


TRegistry::RenameValue

TRegistry	See also

Changes the name of a data value associated with the current key.

void __fastcall RenameValue(const System::AnsiString OldName, const System::AnsiString NewName);

Description

Call RenameValue to change the name of a data value associated with the current key. OldName is a string containing the current name of the data value. NewName is a string containing the replacement name for the data value.

If OldName is the name of an existing data value for the current key, and NewName is not the name of an existing data value for the current key, RenameValue changes the data value name as specified. Otherwise the current name remains unchanged.


TRegistry::ReplaceKey

TRegistry	See also

Replaces the hive file backing a key and all its subkeys with a hive stored in a different file, so that when the system is next started, the key and subkeys will have the values stored in the new file.

bool __fastcall ReplaceKey(const System::AnsiString Key, const System::AnsiString FileName, const System::AnsiString BackUpFileName);

Description

Call ReplaceKey to replace the hive file backing a key and all its subkeys with a different hive file. A hive is a discrete collection of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

FileName indicates the name of the file containing the new key and subkey information. BackUpFileName is the name of a backup file used to store the current key and subkey information before it is overwritten.

ReplaceKey returns true if it is successful.

Note:	The file specified by FileName parameter must be created with the SaveKey function, or by directly calling the Windows 95/NT RegSaveKey API function. Under the FAT file system FileName cannot have an extension.


TRegistry::RestoreKey

TRegistry	See also

Reopens the specified key, and overwrites any information contained in this key and its subkeys keys with registry data stored in a hive file.

bool __fastcall RestoreKey(const System::AnsiString Key, const System::AnsiString FileName);

Description

Call RestoreKey to open the specified key with a security access value of KEY_ALL_ACCESS and overwrite any information in the key and its subkeys with registry data stored in a hive file. A hive is a discrete collection of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Key is the name of the key to open. FileName is the name of the file containing the hive information.

If RestoreKey successfully reads and copies the registry information in FileName to the specified key, the return value of RestoreKey is true and the key is closed.

Note:	The file specified by FileName parameter must be created with the SaveKey function, or by directly calling the Windows 95/NT RegSaveKey API function. Under the FAT file system FileName cannot have an extension.


TRegistry::SaveKey

TRegistry	See also

Opens the specified key with the security access value KEY_ALL_ACCESS and saves the specified key and all of its subkeys and values to a hive file.

bool __fastcall SaveKey(const System::AnsiString Key, const System::AnsiString FileName);

Description

Call SaveKey to open a key with a security access value of KEY_ALL_ACCESS, and save the key and its subkeys and data values to a hive file. A hive is a discrete collection of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Key is the key to save. FileName is the file into which to save the key information. It must be the name of a new file that does not already exist. On FAT file systems FileName cannot include an extension.

Files created by SaveKey are passed as parameters to the RestoreKey, ReplaceKey and LoadKey functions.

If SaveKey is successful it returns true and closes the key.


TRegistry::UnLoadKey

TRegistry	See also

Removes a hive from the registry.

bool __fastcall UnLoadKey(const System::AnsiString Key);

Description

Call UnLoadKey to remove a hive from the registry without modifying its associated hive file, if any. A hive is a discrete collection of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Key is the name of the key at the root of the hive to remove.

If successful, UnLoadKey returns true.

Note:	Before calling this function, set RootKey to HKEY_USERS, HKEY_LOCAL_MACHINE, or call RegistryConnect.


TRegistry::ValueExists

TRegistry	See also

Determines if a specified data value exists for the current key.

bool __fastcall ValueExists(const System::AnsiString Name);

Description

Call ValueExists to determine if a particular key exists in the registry. Calling Value Exists is especially useful before calling other TRegistry methods that operate only on existing keys.

Name is the name of the data value for which to check.

ValueExists returns true if a match if found, false otherwise.


TRegistry::WriteBinaryData

TRegistry	See also

Stores an Object Pascal record in a specifically named data value associated with the current key.

void __fastcall WriteBinaryData(const System::AnsiString Name, void *Buffer, int BufSize);

Description

Call WriteBinaryData to store an Object Pascal record in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteBinary. If Name does not exist, it is created.

Buffer is an Object Pascal record or data buffer containing the data to store in the registry. BufSize indicates the size of Buffer.

Note:	Data-value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as separate files, and those file names should be stored in the registry. Application elements such as icons, bitmaps, and executable files should be stored as separate files rather than as values in the registry.

If WriteBinaryData fails, an exception is raised, and the value is not written to the registry.


TRegistry::WriteBool

TRegistry	See also

Stores a Boolean value in a specifically named data value associated with the current key.

void __fastcall WriteBool(const System::AnsiString Name, bool Value);

Description

Call WriteBool to store an Object Pascal Boolean value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteBool. If Name does not exist, it is created.

Value is an Object Pascal Boolean value to store in the registry.

If WriteBool fails, an exception is raised, and the value is not written to the registry.


TRegistry::WriteCurrency

TRegistry	See also

Stores a currency value in a specifically named data value associated with the current key.

void __fastcall WriteCurrency(const System::AnsiString Name, System::Currency Value);

Description

Call WriteCurrency to store an Object Pascal Currency value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteCurrency. If Name does not exist, it is created.

Value is an Object Pascal Currency value to store in the registry.

If WriteCurrency fails, an exception is raised, and the value is not written to the registry.


TRegistry::WriteDate

TRegistry	See also

Stores a date value in a specifically named data value associated with the current key.

void __fastcall WriteDate(const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteDate to store an Object Pascal datetime value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteDate. If Name does not exist, it is created.

Value is an Object Pascal datetime value to store in the registry.

If WriteDate fails, an exception is raised, and the value is not written to the registry.

If successful, WriteDate stores a C++Builder TDateTime value. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is the time of day.


TRegistry::WriteDateTime

TRegistry	See also

Stores a datetime value in a specifically named data value associated with the current key.

void __fastcall WriteDateTime(const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteDateTime to store an Object Pascal datetime value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteDateTime. If Name does not exist, it is created.

Value is an Object Pascal datetime value to store in the registry.

If WriteDateTime fails, an exception is raised, and the value is not written to the registry.

If successful, WriteDateTime stores a C++Builder TDateTime value. The integral part of a TDateTime value is the number of days that have passed since12/30/1899. The fractional part of a TDateTime value is the time of day.


TRegistry::WriteFloat

TRegistry	See also

Stores a Double value in a specifically named data value associated with the current key.

void __fastcall WriteFloat(const System::AnsiString Name, double Value);

Description

Call WriteFloat to store an Object Pascal float value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteFloat. If Name does not exist, it is created.

Value is an Object Pascal float value to store in the registry.

If WriteFloat fails, an exception is raised, and the value is not written to the registry.


TRegistry::WriteInteger

TRegistry	See also

Stores an integer value in a specifically named data value associated with the current key.

void __fastcall WriteInteger(const System::AnsiString Name, int Value);

Description

Call WriteInteger to store an Object Pascal integer value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteInteger. If Name does not exist, it is created.

Value is an Object Pascal integer value to store in the registry.

If WriteInteger fails, an exception is raised, and the value is not written to the registry.


TRegistry::WriteString

TRegistry	See also

Stores an integer value in a specifically named data value associated with the current key.

void __fastcall WriteString(const System::AnsiString Name, const System::AnsiString Value);

Description

Call WriteString to store an Object Pascal string value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteString. If Name does not exist, it is created.

Value is an Object Pascal string value to store in the registry.

If WriteString fails, an exception is raised, and the value is not written to the registry.


TRegistry::WriteTime

TRegistry	See also

Stores a time value in a specifically named data value associated with the current key.

void __fastcall WriteTime(const System::AnsiString Name, System::TDateTime Value);

Description

Call WriteTime to store an Object Pascal datetime value in a data value associated with the current key.

Name is a string containing the name of the data value in which to store data. If Name already exists, its current value is overwritten by WriteTime. If Name does not exist, it is created.

Value is an Object Pascal datetime value to store in the registry.

If WriteTime fails, an exception is raised, and the value is not written to the registry.

If successful, WriteTime stores a C++Builder TDateTime value. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is the time of day.


Accessibility

Read-only


Hierarchy

TObject


 TRemoteServer

Hierarchy	Properties	Methods	Events	See also

TRemoteServer handles a remote server connection in a client application that is part of a multi-tiered application.

Unit

dbclient

Description

TRemoteServer is used in the client portion of a multi-tiered database application to establish and maintain the connection between the client and a remote application server. The remote server object can

•	Connect to a remote application server.

•	Provide a list of provider names available to client datasets through this connection.

•	Obtain an IProvider interface based on a provider name.

•	Maintain a list of local client datasets that can be serviced through this connection.

•	Disconnect from the remote application server.

The remote server object establishes the initial connection between the client application and a remote application server using DCOM. Once the connection is established, the client registers any or all of its client datasets with the remote server, and these client datasets can then communicate directly with the application server’s TProvider object through its IProvider interface.

To connect client applications to remote application servers using TCP/IP sockets or OLEnterprise instead of DCOM, use the TMIDASConnection component.


TRemoteServer properties

TRemoteServer	Alphabetically	Legend

In TRemoteServer

AppServer

ComputerName

Connected

ServerGUID

ServerName

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TRemoteServer properties

TRemoteServer	By object	Legend

AppServer

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ComputerName

Connected

DesignInfo

Name

Owner

ServerGUID

ServerName

Tag

VCLComObject


TRemoteServer::AppServer

TRemoteServer	See also

Indicates the Variant containing an interface returned to the remote server.

__property System::Variant AppServer = {read=GetAppServer};

Description

AppServer is a read-only property that points to the interface returned to the remote server by an application server’s provider component. Client applications can communicate directly with the application server through this interface.


TRemoteServer::ComputerName

TRemoteServer	See also

Specifies the name of the machine on which a multi-tiered application’s application server is located.

__property System::AnsiString ComputerName = {read=FComputerName, write=SetComputerName};

Description

Set ComputerName to the machine name of the computer where the application server resides. If ComputerName is blank (the default), C++Builder assumes the application server can be found on the user’s machine or that the computer name can be derived from the system registry based on DCOM or OLE Enterprise configuration. Normally the client and the application server run on different machines, so ComputerName must be set by one of these methods.

Note:	Some descendants of TRemoteServer, such as TMIDASConnection, use the ComputerName property for other purposes, such as the IP Address of the server machine or the OLEnterprise server name.


TRemoteServer::Connected

TRemoteServer	See also

Indicates whether the remote server object is connected to a remote application server.

__property bool Connected = {read=GetConnected, write=SetConnected, default=0};

Description

Use Connected to read or set the current connection status for a remote server object. By default, Connected is false.


TRemoteServer::ServerGUID

TRemoteServer	See also

Specifies the name of the GUID of the application server to which the remote server connects.

__property System::AnsiString ServerGUID = {read=GetServerGUID, write=SetServerGUID};

Description

Use ServerGUID to specify the application server to which the remote server object should connect by its GUID. If the value specifies a valid GUID for a registered application server, setting ServerGUID changes the value of ServerName to the class name of the corresponding COM object.

Note:	When using DCOM to establish connections, either ServerName or ServerGUID must be provided so that the remote server can determine what server it should connect to.


TRemoteServer::ServerName

TRemoteServer	See also

Specifies the name of the application server to which the remote server connects.

__property System::AnsiString ServerName = {read=FServerName, write=SetServerName, stored=StoreServerName};

Description

Use ServerName to specify the name of the application server to which the remote server object should connect. At design time, the developer can choose an available server from the drop-down list for this property in the Object Inspector.

Setting ServerName sets the ServerGUID property to the GUID that corresponds to the named application server.

Note:	When using DCOM to establish connections, either ServerName or ServerGUID must be provided so that the remote server can determine what server it should connect to.


TRemoteServer events

TRemoteServer	Alphabetically	Legend

Derived from TCustomRemoteServer

AfterConnect

AfterDisconnect

BeforeConnect

BeforeDisconnect


TRemoteServer events

TRemoteServer	By object	Legend

AfterConnect

AfterDisconnect

BeforeConnect

BeforeDisconnect


TRemoteServer methods

TRemoteServer	Alphabetically	Legend

In TRemoteServer

~TRemoteServer

DoConnect

DoDisconnect

GetConnected

GetProvider

GetProviderNames

TRemoteServer

Derived from TCustomRemoteServer

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRemoteServer methods

TRemoteServer	By object	Legend

~TRemoteServer

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

DoConnect

DoDisconnect

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetConnected

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetProvider

GetProviderNames

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TRemoteServer


TRemoteServer::DoConnect

TRemoteServer	See also

Connects to an application server.

virtual void __fastcall DoConnect(void);

Description

DoConnect is called internally by SetConnected. DoConnect establishes an ActiveX dual interface between the remote server and a provider object on the application server.


TRemoteServer::DoDisconnect

TRemoteServer	See also

Drops a connection to an application server.

virtual void __fastcall DoDisconnect(void);

Description

DoDisconnect is called internally by SetConnected. DoDisconnect drops the connection to an application server.


TRemoteServer::GetConnected

TRemoteServer	See also

Reads the Connected property.

virtual bool __fastcall GetConnected(void);

Description

GetConnected determines if the remote server is connected to an application server. The value returned by GetConnected becomes the current setting of the Connected property.

If GetConnected returns true, a connection is established. Otherwise, GetConnected returns false.


TRemoteServer::GetProvider

TRemoteServer	See also

Returns an IProvider interface implemented by the provider object on the application server in response to a client application connection request.

virtual Stdvcl::_di_IProvider __fastcall GetProvider(const System::AnsiString ProviderName);

Description

Call GetProvider to return an IProvider corresponding to the ProviderName parameter. The IProvider interface returned by GetProvider is subsequently used by client datasets to communicate directly with the provider object for data exchange.

ProviderName is the name of the property on the application server which returns the IProvider interface.


TRemoteServer::GetProviderNames

TRemoteServer	See also

Retrieves a list of all available provider objects from an application server into a list created and maintained by the remote server.

typedef void __fastcall (__closure *TGetStrProc)(const System::AnsiString S);

virtual void __fastcall GetProviderNames(Classes::TGetStrProc &Proc);

Description

Call GetProviderNames to return a list of all available IProvider interfaces established by the application server. Interfaces can then be made available to client datasets that use this remote server.

List is a string list, created and maintained by the client application, into which a list of IProvider interfaces is stored.


TRemoteServer::TRemoteServer

TRemoteServer

Creates a new TRemoteServer object.

__fastcall virtual TRemoteServer(Classes::TComponent* AOwner) : Dbclient::TCustomRemoteServer(AOwner) { }

Description

Use TRemoteServer indirectly, using the new keyword, to create a remote server component at runtime. Usually remote server components are added to forms or data modules at design time and created automatically.


TRemoteServer::~TRemoteServer

TRemoteServer

~TRemoteServer frees the memory associated with the TRemoteServer object.

__fastcall virtual ~TRemoteServer(void) { }

Description

Do not call ~TRemoteServer directly. Instead, use the delete keyword on the object, which causes ~TRemoteServer to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCustomRemoteServer


 TReplaceDialog

Hierarchy	Properties	Methods	Events	See also

TReplaceDialog displays a search-and-replace dialog.

Unit

dialogs

Description

TReplaceDialog is a special version of TFindDialog that prompts the user for both a search string and a replace string. Like the Find dialog, the Replace dialog is modeless and does not appear at runtime until activated by a call to the Execute method.


TReplaceDialog properties

TReplaceDialog	Alphabetically	Legend

In TReplaceDialog

ReplaceText

Derived from TFindDialog

FindText

Left

Options

Position

Top

Derived from TCommonDialog

Ctl3D

Handle

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TReplaceDialog properties

TReplaceDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Ctl3D

DesignInfo

FindText

Handle

HelpContext

Left

Name

Options

Owner

Position

ReplaceText

Tag

Top

VCLComObject


TReplaceDialog::ReplaceText

TReplaceDialog	See also 	Example

Contains the text that should replace FindText.

__property System::AnsiString ReplaceText = {read=GetReplaceText, write=SetReplaceText};

Description

FindText, taken from the Find What edit box, contains the text string that the user wants to search for. ReplaceText, taken from the Replace With edit box, contains the text string that will replace FindText. To make a default text string appear in the Replace With edit box when the dialog opens, assign a value to ReplaceText in the Object Inspector or in program code.


TReplaceDialog events

TReplaceDialog	Alphabetically	Legend

In TReplaceDialog

OnReplace

Derived from TFindDialog

OnFind

Derived from TCommonDialog

OnClose

OnShow


TReplaceDialog events

TReplaceDialog	By object	Legend

OnClose

OnFind

OnReplace

OnShow


TReplaceDialog::OnReplace

TReplaceDialog	See also 	Example

OnReplace occurs when the user clicks the Replace or Replace All button.

__property Classes::TNotifyEvent OnReplace = {read=FOnReplace, write=FOnReplace};

Description

OnReplace occurs whenever the user clicks Replace or Replace All. In addition, when the user clicks Replace, the frReplace flag is set (and the frReplaceAll flag is turned off) in Options. When the user clicks ReplaceAll, the frReplaceAll flag is set (and the frReplace flag is turned off) in Options.

Write an OnReplace event handler that searches for the text specified in FindText and replaces it with the text in ReplaceText. Use the Options flags to determine how the search is conducted.


TReplaceDialog methods

TReplaceDialog	Alphabetically

In TReplaceDialog

~TReplaceDialog

TReplaceDialog

Derived from TFindDialog

CloseDialog

Execute

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TReplaceDialog methods

TReplaceDialog	By object

~TReplaceDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CloseDialog

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TReplaceDialog


TReplaceDialog::TReplaceDialog

TReplaceDialog	See also

Creates and initializes a TReplaceDialog instance.

__fastcall virtual TReplaceDialog(Classes::TComponent* AOwner);

Description

Do not call TReplaceDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.

The TReplaceDialog method generates a TReplaceDialog instance, but the new dialog does not appear on the form at runtime until the Execute method is called.


TReplaceDialog::~TReplaceDialog

TReplaceDialog

~TReplaceDialog frees the memory associated with the TReplaceDialog object.

__fastcall virtual ~TReplaceDialog(void) { }

Description

Do not call ~TReplaceDialog directly. Instead, use the delete keyword on the object, which causes ~TReplaceDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog

TFindDialog


TWebRequest

Hierarchy	Properties	Methods	See also

TWebRequest is a base class for all objects that represent client request information that is passed to a Web server application.

Unit

httpapp

Description

Use a descendant of TWebRequest to interpret an HTTP request message.

Web application objects create TWebRequest objects to capture client requests. The properties of the TWebRequest objects are obtained from the HTTP request message. The Web application uses TWebRequest objects to create corresponding TWebResponse objects. The TWebDispatcher for the application then invokes the TWebActionItem that is associated with the PathInfo of the TWebRequest object.

TWebRequest has three descendants, which represent client requests for different types of Web server applications. These descendants are

•	TISAPIRequest objects for DLLs that respond to the ISAPI or NSAPI servers.

•	TCGIRequest objects for CGI server applications.

•	TWinCGIRequest objects for Windows-based CGI servers.


TWebRequest properties

TWebRequest	Alphabetically	Legend

In TWebRequest

Accept

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentFields

ContentLength

ContentType

ContentVersion

Cookie

CookieFields

Date

DerivedFrom

Expires

From

Host

IfModifiedSince

Method

MethodType

PathInfo

PathTranslated

ProtocolVersion

Query

QueryFields

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent


TWebRequest properties

TWebRequest	By object	Legend

Authorization

CacheControl

Connection

Content

ContentEncoding

ContentFields

ContentLength

ContentType

ContentVersion

Cookie

CookieFields

Date

DerivedFrom

Expires

From

Host

IfModifiedSince

Method

MethodType

PathInfo

PathTranslated

ProtocolVersion

Query

QueryFields

Referer

RemoteAddr

RemoteHost

ScriptName

ServerPort

Title

URL

UserAgent

Accept


TWebRequest::Accept

TWebRequest	See also

Reports the value of the Accept header of the HTTP request message.

__property System::AnsiString Accept = {read=GetStringVariable, index=8};

Description

Read Accept to determine the media types the Web client can accept in response to the request. Not every HTTP request message has an Accept header. If the Accept property is not set, then any media type is potentially acceptable in the response.

Accept headers usually indicate that the response should be limited to a small set of desired types. For example, a Web client requesting an audio response might produce a TWebRequest object with Accept set to the following string:

audio/*; q=0.2, audio/basic

This request indicates that the preferred response media type is audio/basic, but that any audio type is acceptable if it is the best available after an 80% mark-down in quality.

For information on the format of Accept headers, see the current Internet standards documentation.


TWebRequest::Authorization

TWebRequest	See also

Reports the value of the Authorization header of the HTTP request message.

__property System::AnsiString Authorization = {read=GetStringVariable, index=28};

Description

Read Authorization to check whether the client that sent the request message has provided the correct authentication information. Authorization allows the Web application to provided limited access to the resource specified by the URL property.

For more information about HTTP authentication schemes, see the Internet standards documentation.


TWebRequest::CacheControl

TWebRequest 	See also

Reports the value of the Cache-Control header of the HTTP request message.

__property System::AnsiString CacheControl = {read=GetStringVariable, index=6};

Description

Read CacheControl to determine any Web client directives that must be obeyed by all caching mechanisms along the request/response chain. The CacheControl directives of the HTTP request need not apply to the corresponding HTTP response.

The HTTP 1.1 standard defines the following directives for CacheControl:

Value	Meaning

no-cache	The request may not be cached. The Web server validates the request before the TWebRequest object is created.

no-store	The request contains sensitive information and may not be stored on any permanent medium such as a backup tape. If the request is stored temporarily in a file, the file must be deleted.

max-age=ss	The request is considered invalid if it is older than ss seconds. This directive takes precedence over the Expires property, even if Expires is more restrictive. Invalid requests are validated by the Web server before the TWebRequest object is created.

max-stale or max-stale=ss	The client is willing to accept a response that has exceeded its expiration time. The max-stale directive can optionally specify the number of seconds by which the response can exceed it’s expiration time.

min-fresh=ss	The client is not willing to accept a response that expires in less than ss seconds.


TWebRequest::Connection

TWebRequest	See also

Reports the value of the Connection header of the HTTP request message.

__property System::AnsiString Connection = {read=GetStringVariable, index=26};

Description

Read Connection to determine the options requested by the Web client for its connection to the server application. The HTTP 1.1 standard specifies only one value for the Connection header. If the value of Connection is close, the connection should be closed after the completion of the response.


TWebRequest::Content

TWebRequest	See also

Represents the unparsed contents of the HTTP request message.

__property System::AnsiString Content = {read=GetStringVariable, index=25};

Description

Use Content to read the contents of an HTTP request message that is sending information to the server. The value of Content depends on the Method of the HTTP request. When the Method is POST, Content is the unparsed string giving the values to be posted with their associated fields. When the Method is PUT, Content is the value that should replace the URL given by the URL property.

Note:	When the Method is POST, the parsed version of the post request is available in the ContentFields property.


TWebRequest::ContentEncoding

TWebRequest	See also

Reports the value of the Content-Encoding header of the HTTP request message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, index=14};

Description

Read ContentEncoding to determine what encoding mechanisms, if any, have been applied to the Content of the HTTP request. The encoding mechanisms are listed in the order in which they were applied by the Web client, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding scheme used to transfer extended ASCII characters over the net.

Reverse the ContentEncoding mechanisms to decode the Content into the form indicated by the ContentType property.


TWebRequest::ContentFields

TWebRequest	See also

Reports the parsed content of a POST request message.

__property Classes::TStrings* ContentFields = {read=GetContentFields};

Description

Use ContentFields to read the fields of an HTTP request message when the MethodType is mtPost. The Content of the HTTP request is parsed, separating into fields at the ampersand character.

Each field appears as a separate string in the ContentFields list with the form Name=Value. As a TStrings object, ContentFields allows applications to manipulate the individual fields by name or value.


TWebRequest::ContentLength

TWebRequest	See also

Reports the value of the Content-Length header of the HTTP request message.

__property int ContentLength = {read=GetIntegerVariable, index=16, nodefault};

Description

Read the ContentLength property to determine the length of the Content property. ContentLength allows an application to determine the end of the Content property when the ContentType is not text/html. A ContentLength of 0 indicates that the length of the Content property is not determined, either because the request does not include any Content, or because the Web client did not know the length.

Note:	The length of the Content may be less than ContentLength when the Content is passed by chunked transfer coding.


TWebRequest::ContentType

TWebRequest	See also

Reports the value of the Content-Type header of the HTTP request message.

__property System::AnsiString ContentType = {read=GetStringVariable, index=15};

Description

Read ContentType to determine the media type of the Content of the HTTP request message. The ContentType is a string of the form Type/SubType.

Most HTTP requests do not require any Content at all. For most requests with a Method that requires a value for Content, the ContentType is text/html. However, HTTP requests for server-specific values of Method can use any media type appropriate to the request.


TWebRequest::ContentVersion

TWebRequest	See also

Reports the value of the Content-Version header of the HTTP request message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, index=17};

Description

Read ContentVersion to determine the version of the Content of the HTTP request message. Most HTTP requests do not require any Content at all. When the Method requires a value for Content, the ContentVersion may be set to indicate the version of the source of that content. The format of the ContentVersion depends on the ContentType of the request.


TWebRequest::Cookie

TWebRequest	See also

Reports the value of the Cookie header of the HTTP request message.

__property System::AnsiString Cookie = {read=GetStringVariable, index=27};

Description

Use Cookie to read the “cookie” strings provided in the Web client request. Cookie strings are used to track state information in a Web application. Cookie is the unparsed value of the Cookie header. The Cookie header can include multiple fields separated by semicolons. Use the CookieFields property to work with the Cookie header on a field-by-field basis.


TWebRequest::CookieFields

TWebRequest	See also

Represents the parsed contents of the Cookie header of an HTTP request message.

__property Classes::TStrings* CookieFields = {read=GetCookieFields};

Description

Use CookieFields to work with individual “cookie” strings provided by the Web client request. The Cookie property is parsed into separate fields by separating into substrings whenever a semicolon is encountered.

Cookie strings are used to track state information in a Web application. Each field appears as a separate string in the CookieFields list with the form Name=Value. As a TStrings object, CookieFields allows applications to manipulate the individual fields by name or value.

Note:	Applications can give state variables any name except one of the reserved cookie field names. See the Netscape documentation for a list of reserved cookie field names and their meanings.


TWebRequest::Date

TWebRequest 	See also

Reports the value of the Date header of the HTTP request message.

__property System::TDateTime Date = {read=GetDateVariable, index=7};

Description

Read Date to determine the date and time at which the HTTP request message originated. Date can be used to determine whether the Content of the request is still valid. The value of Date is translated into local time as specified in the Windows Control Panel from the time units set by the Web client.

For example, if an HTTP request message specifies a MethodType of mtPost, and Date is older than the most recent values of the fields that are being posted, the server application may return a status code that indicates an error rather than overwriting more recent values.

Date is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TWebRequest::DerivedFrom

TWebRequest	See also

Reports the value of the Derived-From header of the HTTP request message.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, index=18};

Description

Read DerivedFrom to determine the URI from which the value of Content originated. DerivedFrom is only meaningful when the request includes a Content property and the Content did not originate with the Web client.


TWebRequest::Expires

TWebRequest 	See also

Reports the value of the Expires header of the HTTP request message.

__property System::TDateTime Expires = {read=GetDateVariable, index=19};

Description

Use Expires to determine whether the request is “stale.” Expires is the date and time at which the request becomes invalid. The value of Expires is translated into local time as specified in the Windows Control Panel from the time units set by the Web client.

If the request has a CacheControl value with a max-age directive, the max-age directive overrides the value of Expires.

Expires is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TWebRequest::From

TWebRequest	See also

Reports the value of the From header of the HTTP request message.

__property System::AnsiString From = {read=GetStringVariable, index=9};

Description

Read From to determine the Internet e-mail address of the human user for whom the Web client sent the HTTP request message. This value can be used for logging purposes, or to contact the originator of the request if problems occur.


TWebRequest::Host

TWebRequest	See also

Reports the value of the Host header of the HTTP request message.

__property System::AnsiString Host = {read=GetStringVariable, index=10};

Description

Read Host to determine the Internet host and port number of resource being requested. For example, if the client request specifies the following URL:

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

The value of Host would be

www.TSite.com

The value of Host can be used to differentiate between internally ambiguous URLs, such as the root “/” URL of a server for multiple host names on a single IP address.


TWebRequest::IfModifiedSince

TWebRequest 	See also

Reports the value of the If-Modified-Since header of the HTTP request message.

__property System::TDateTime IfModifiedSince = {read=GetDateVariable, index=11};

Description

Read IfModifiedSince on a request with an HTTPMethod of mtGet to determine whether the request is conditional. If the information requested by the Web client was not modified since the time indicated by IfModifiedSince, the response should be a not modified error rather than the information indicated by the URL property.

The value of IfModifiedSince is given according to the local clock as specified in the Windows Control Panel, not the clock of the Web client.

IfModifiedSince is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24-hour day that has elapsed.


TWebRequest::Method

TWebRequest	See also

Reports the value of the Method header of the HTTP request message.

__property System::AnsiString Method = {read=GetStringVariable, index=0};

Description

Read Method to determine the method that is requested by the Web client. The HTTP 1.1 standard defines the following methods

Value	Meaning

OPTIONS	A request for information about available communication options.

GET	A request for the information identified by the URL property.

HEAD	A request for information about the properties of the HTTP response, but not for the content of the response.

POST	A request for the server application to post the data included in the Content property, as appropriate.

PUT	A request for the server application to replace the resource indicated by the URL property with the data included in the Content property.

DELETE	A request for the server application to delete or hide the resource identified by the URL property.

TRACE	A request for the server application to send a loop-back to confirm receipt of the request.

The Method property may indicate any other method that the Web client requests of the server. If the Method can’t be matched to the Allow property of a TWebResponse object, the request can’t be serviced.

Note:	The MethodType property indicates whether the value of Method is GET, HEAD, POST, PUT, or one of the other strings. When possible, use MethodType instead of the Method property to save the overhead of string comparison.

Note:	An HTTP application does not need to service all method types. However, there must be a response for the GET and HEAD method requests.


TWebRequest::MethodType

TWebRequest	See also

Indicates the method requested by the Web client.

__property TMethodType MethodType = {read=FMethodType, nodefault};

Description

Read MethodType to determine the type of response that is requested by the Web client. The value of MethodType is one of the following:

Value	Meaning

mtGet	A request for the information identified by the URL property.

mtHead	A request for information about the properties of the HTTP response, but not for the content of the response.

mtPost	A request for the server application to post the data in the Content property, as appropriate.

mtPut	A request for the server application to replace the resource identified by the URL property with the value of Content.

mtAny	Any other type of request.

If the MethodType is mtAny, read the Method property to determine the method requested by the Web client.


TWebRequest::PathInfo

TWebRequest	See also

Reports the value of the path information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString PathInfo = {read=GetStringVariable, index=4};

Description

Read PathInfo to determine the path on the server machine where the target of the request is found. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the PathInfo portion is

/mammals

The TWebDispatcher object uses the PathInfo to identify the appropriate TWebActionItem for servicing the request message.


TWebRequest::PathTranslated

TWebRequest	See also

Represents a translation of the PathInfo property to a fully qualified path on the Web server.

__property System::AnsiString PathTranslated = {read=GetStringVariable, index=5};

Description

Use PathTranslated to refer to the location of the target of the request in an HTTP response.


TWebRequest::ProtocolVersion

TWebRequest	See also

Reports the version number of the HTTP protocol specified in the initial header of the HTTP request message.

__property System::AnsiString ProtocolVersion = {read=GetStringVariable, index=1};

Description

Use ProtocolVersion to determine the protocol used by the Web client when generating the HTTP request message.

Some properties of the HTTP request may be interpreted differently depending on the ProtocolVersion. For example, if ProtocolVersion is 1.0, then the connection should not be considered persistent, even if the Connection property does not specify the close option.


TWebRequest::Query

TWebRequest	See also

Indicates the value of the query information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString Query = {read=GetStringVariable, index=3};

Description

Read Query to determine the details of a query specified in the URL of the Web client request. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the Query portion is

animal=dog&color=black

Query is the unparsed query portion of the URL. The query may include multiple fields separated by ampersands. Use the QueryFields property to work with the query on a field-by-field basis.


TWebRequest::QueryFields

TWebRequest	See also

Represents the parsed contents of the Query in the URL of the HTTP request message.

__property Classes::TStrings* QueryFields = {read=GetQueryFields};

Description

Use QueryFields to work with individual query values provided by the Web client request. The Query property is parsed into separate fields by separating into substrings whenever an ampersand is encountered.

Each query field appears as a separate string in the QueryFields list with the form Name=Value. As a TStrings object, QueryFields allows applications to manipulate the individual fields by name or value.


TWebRequest::Referer

TWebRequest	See also

Reports the value of the Referer header of the HTTP request message.

__property System::AnsiString Referer = {read=GetStringVariable, index=12};

Description

Read Referer to determine the URI of the resource where the HTTP request message originated. Referer allows the server application to generate back-links to the source of the request. If Referer is a partial URI, it should be interpreted as a relative path to the URL property.

The Referer property is not set when the URL of the HTTP request was obtained from a source that does not have its own URI, such as input from the user keyboard.


TWebRequest::RemoteAddr

TWebRequest	See also

Indicates the remote IP address of the client associated with the HTTP request message.

__property System::AnsiString RemoteAddr = {read=GetStringVariable, index=21};

Description

Read RemoteAddr to obtain the IP address of the source of the Web client request.


TWebRequest::RemoteHost

TWebRequest	See also

Reports the fully qualified reverse domain lookup of the client associated with the HTTP request message.

__property System::AnsiString RemoteHost = {read=GetStringVariable, index=22};

Description

Use RemoteHost to compose URI values for back-links to the source of the request when the Referer property is not specified. RemoteHost does not include any path information.


TWebRequest::ScriptName

TWebRequest	See also

Indicates the value of the script information (if any) of the URL specified in the HTTP request message.

__property System::AnsiString ScriptName = {read=GetStringVariable, index=23};

Description

Read ScriptName to determine the full path to the Web server application specified by the client request. For example, given this URL

http://www.TSite.com/art/gallery.dll/mammals?animal=dog&color=black

and assuming that the /gallery.dll part is the Web server application, the ScriptName portion is

/art/gallery


TWebRequest::ServerPort

TWebRequest	See also

Indicates the port number of the port on the Web server that receives the HTTP request message.

__property int ServerPort = {read=GetIntegerVariable, index=24, nodefault};

Description

Read ServerPort to determine the number of the port used in the connection to the Web server. The Host property will include the ServerPort if it is specified as part of the URL for the client request.


TWebRequest::Title

TWebRequest	See also

Reports the value of the Title header of the HTTP request message.

__property System::AnsiString Title = {read=GetStringVariable, index=20};

Description

Read Title to determine the Title of the information requested in the Web client request.


TWebRequest.URL
TWebRequest::URL

TWebRequest	See also

Reports the Uniform Resource Identifier (URI) specified by the HTTP request message to identify the target of the request.

__property System::AnsiString URL = {read=GetStringVariable, index=2};

Description

Use the URL property to identify the resource the Web client identifies as the target of the request message. URL may be an HTML page to return, a resource to be created or deleted, or an object that provides some other service for the Web client.

The TWebRequest object parses the URL into its constituent parts, yielding the Host, ScriptName, PathInfo, and Query properties.

Note:	Usually the URL property is a Uniform Resource Locator (URL) that can be parsed into host, script, path, and query portions. However, it is possible for HTTP request messages to specify the target in more general terms, as a Uniform Resource Identifier (URI).


TWebRequest::UserAgent

TWebRequest	See also

Reports the value of the User-Agent header of the HTTP request message.

__property System::AnsiString UserAgent = {read=GetStringVariable, index=13};

Description

Read UserAgent to obtain information about the user agent originating the client request. Use the UserAgent information for statistical purposes, for tracing protocol violations, and for tailoring responses to known limitations of specific applications that generate client requests. The UserAgent string contains one or more descriptors, in order of significance. Each descriptor gives the name of the product or application that generated the request, or a comment about the user agent.


TWebRequest methods

TWebRequest	Alphabetically	Legend

In TWebRequest

~TWebRequest

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

GetDateVariable

GetFieldByName

GetIntegerVariable

GetStringVariable

ReadClient

ReadString

TranslateURI

TWebRequest

WriteClient

WriteString

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWebRequest methods

TWebRequest	By object	Legend

~TWebRequest

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

ExtractContentFields

ExtractCookieFields

ExtractFields

ExtractQueryFields

FieldAddress

Free

FreeInstance

GetDateVariable

GetFieldByName

GetIntegerVariable

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ReadClient

ReadString

SafeCallException

TranslateURI

TWebRequest

WriteClient

WriteString


TWebRequest::TWebRequest

TWebRequest	See also

Creates an instance of TWebRequest.

__fastcall TWebRequest(void);

Description

Applications shouldn’t need to call TWebRequest to instantiate a request object. The TWebApplication object creates a TWebRequest object whenever it receives a client request.


TWebRequest::~TWebRequest

TWebRequest	See also

Destroys an instance of TWebRequest.

__fastcall virtual ~TWebRequest(void);

Description

Do not call ~TWebRequest. When the request message is fully handled, TWebApplication destroys the request object by using the delete keyword.

~TWebRequest frees the TStrings objects used to represent the ContentFields, CookieFields, and QueryFields properties.


TWebRequest::ExtractContentFields

TWebRequest	See also

Parses the Content property into its constituent fields.

void __fastcall ExtractContentFields(Classes::TStrings* Strings);

Description

Call ExtractContentFields to fill the Strings parameter with the individual fields in the Content property. ExtractContentFields assumes that fields are separated by ampersands. This is the format used when the MethodType is mtPost. If the Content property is not assigned, ExtractContentFields does nothing.


TWebRequest::ExtractCookieFields

TWebRequest	See also

Parses the Cookie property into its constituent fields.

void __fastcall ExtractCookieFields(Classes::TStrings* Strings);

Description

Call ExtractCookieFields to fill the Strings parameter with the individual fields in the Cookie property. ExtractCookieFields assumes that fields are separated by semicolons. If the Cookie property is not assigned, ExtractCookieFields does nothing.


TWebRequest::ExtractFields

TWebRequest	See also

Parses a multi-valued string into its constituent fields.

void __fastcall ExtractFields(const TCharSet &Separators, const TCharSet &WhiteSpace, char * Content, Classes::TStrings* Strings);

Description

Call ExtractFields to parse a multi-valued HTTP header into separate strings for each value. For example, if the separator character of the UserAgent property is known, ExtractFields can parse this property into separate UserAgent values.

Separators is a set of characters that are used to separate individual values within the multi-valued string. WhiteSpace is a set of characters that are to be ignored when parsing the string. Content is the multi-valued string to be parsed. Strings is the TStrings object that receives the individual values that are parsed from Content.


TWebRequest::ExtractQueryFields

TWebRequest	See also

Parses the Query property into its constituent fields.

void __fastcall ExtractQueryFields(Classes::TStrings* Strings);

Description

Call ExtractQueryFields to fill the Strings parameter with the individual fields in the Query property. ExtractQueryFields assumes that fields are separated by ampersands. If the Query property is not assigned, ExtractQueryFields does nothing.


TWebRequest::GetDateVariable

TWebRequest	See also

Provides a pure virtual method for extracting a date value from an indexed table of HTTP header variables.

virtual System::TDateTime __fastcall GetDateVariable(int Index) = 0;

Description

Descendants of TWebRequest implement GetDateVariable to provide a method by which the date-time values are read from the header strings of the HTTP request message. The request object uses GetDateVariable to access the properties that represent dates from the HTTP request headers.


TWebRequest::GetFieldByName

TWebRequest	See also

Provides a pure virtual method that returns the value of the HTTP header variable specified by the Name parameter.

virtual System::AnsiString __fastcall GetFieldByName(const System::AnsiString Name) = 0;

Description

Descendants of TWebRequest impalement GetFieldByName to provide access to arbitrary header fields in the HTTP request message. Use GetFieldByName to read the value of an HTTP header variable that is not surfaced as one of the properties of TWebRequest. For information on possible HTTP request header variables, see the current Internet standards documents.


TWebRequest::GetIntegerVariable

TWebRequest	See also

Provides a pure virtual method for extracting an integer value from an indexed table of HTTP header variables.

virtual int __fastcall GetIntegerVariable(int Index) = 0;

Description

Descendants of TWebRequest implement GetIntegerVariable to provide a method by which the integer values are read from the header strings of the HTTP request message. The request object uses GetIntegerVariable to access the properties that represent integers from the HTTP request headers.


TWebRequest::GetStringVariable

TWebRequest	See also

Provides a pure virtual method for extracting a string value from an indexed table of HTTP header variables.

virtual System::AnsiString __fastcall GetStringVariable(int Index) = 0;

Description

Descendants of TWebRequest implement GetStringVariable to provide a method by which the string values are read from the header strings of the HTTP request message. The request object uses GetStringVariable to access the properties that represent strings from the HTTP request headers.


TWebRequest::ReadClient

TWebRequest	See also

Provides a pure virtual method for reading from the HTTP request into a buffer.

virtual int __fastcall ReadClient(void *Buffer, int Count) = 0;

Description

Descendants of TWebRequest implement ReadClient. ReadClient is used to read content information from the HTTP request. Use ReadClient to get the next chunk of information when the content of the request message is too large for the Content property.

Use Buffer to provide a buffer to contain the content information. Use Count to specify the number of bytes to read. ReadClient returns the number of bytes actually read.


TWebRequest::ReadString

TWebRequest	See also

Provides a pure virtual method for reading Count bytes from the HTTP request into a string.

virtual System::AnsiString __fastcall ReadString(int Count) = 0;

Description

Descendants of TWebRequest implement ReadString. ReadString is used to load content information from the HTTP request into a string. Use ReadString to get the next chunk of information when the content of the request message is too large for the Content property.


TWebRequest::TranslateURI

TWebRequest	See also

Provides a pure virtual method for translating a Uniform Resource Identifier (URI) into an internal representation of a location on the server.

virtual System::AnsiString __fastcall TranslateURI(const System::AnsiString URI) = 0;

Description

Descendants of TWebRequest implement TranslateURI. TranslateURI is used to translate the URI specified in a client request into a format that can be used by the server application. The internal format varies, depending on whether the server application is an ISAPI or NSAPI application. TranslateURI is not relevant to CGI applications.


TWebRequest::WriteClient

TWebRequest	See also

Provides a pure virtual method for writing Count bytes from Buffer back to the HTTP client.

virtual int __fastcall WriteClient(void *Buffer, int Count) = 0;

Description

Descendants of TWebRequest implement WriteClient. WriteClient is used by TWebResponse to send the contents of a response to the Web client.


TWebRequest::WriteString

TWebRequest	See also

Provides a pure virtual method for writing the string AString back to the HTTP client.

virtual bool __fastcall WriteString(const System::AnsiString AString) = 0;

Description

Descendants of TWebRequest implement WriteString. WriteString is used by TWebResponse to send the contents of a response to the Web client.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject


TWebResponse

Hierarchy	Properties	Methods	See also

TWebResponse is an base class for all objects that represent HTTP messages sent in response to an HTTP request message.

Unit

httpapp

Description

Use a descendant of TWebResponse to specify the response to an HTTP request message.

A web application creates a TWebResponse object based on the TWebRequest object for an incoming HTTP request message. The Web dispatcher for the application then passes the TWebResponse object to the TWebActionItem associated with the TWebRequest object, so that the response can be formulated.

TWebResponse has three descendants, which represent HTTP response messages in different types of web server applications. These descendants are

•	TISAPIResponse objects in server DLLs.

•	TCGIResponse objects in CGI server applications.

•	TWinCGIResponse objects in Windows-based CGI servers.


TWebResponse properties

TWebResponse	Alphabetically	Legend

In TWebResponse

Allow

Content

ContentEncoding

ContentLength

ContentStream

ContentType

ContentVersion

Cookies

CustomHeaders

Date

DerivedFrom

Expires

HTTPRequest

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate


TWebResponse properties

TWebResponse	By object	Legend

Content

ContentEncoding

ContentLength

ContentStream

ContentType

ContentVersion

Cookies

CustomHeaders

Date

DerivedFrom

Expires

HTTPRequest

LastModified

Location

LogMessage

Realm

ReasonString

Server

StatusCode

Title

Version

WWWAuthenticate

Allow


TWebResponse::Allow

TWebResponse	See also

Lists the HTTP request methods that the application can service.

__property System::AnsiString Allow = {read=GetStringVariable, write=SetStringVariable, index=5};

Description

Use Allow to indicate what type of request methods the server application can respond to for the URI specified by HTTPRequest. Allow is a string of method names, separated by commas. The method names can include any pre-defined methods from the HTTP standard, or any additional methods implemented by the server application. At a minimum, the TWebResponse object must allow GET and HEAD requests.


TWebResponse::Content

TWebResponse	See also 	Example

Contains the information sent to the web client in response to an HTTP request message.

__property System::AnsiString Content = {read=GetContent, write=SetContent};

Description

Use Content to send requested information to the web client. Not every HTTP request message requires content to be returned. For example, responses to requests with a Method of OPTIONS, HEAD, POST, PUT, DELETE, or TRACE should not include any Content. In all these cases, the response information is contained entirely in the response header, which is built from the other properties of the TWebResponse object.

The response content can be a string of HTML commands, the name of an HTML file, graphic content such as a bit-stream, or any other MIME content type.

Note:	If the ContentStream property is set, it supersedes the value of the Content property. If both Content and ContentStream are set, the web client is sent the value of the ContentStream, not the value of the Content property.


TWebResponse::ContentEncoding

TWebResponse	See also

Lists the mechanisms, if any, that are used to encode the content of the HTTP response message.

__property System::AnsiString ContentEncoding = {read=GetStringVariable, write=SetStringVariable, index=7};

Description

Set ContentEncoding when the value of Content has been encoded before it is sent to the web client. The encoding mechanisms are listed in the order in which they are applied, separated by commas. Typically, ContentEncoding indicates a compression method or an encoding method used to transfer extended-ascii characters over the net.


TWebResponse::ContentLength

TWebResponse	See also

Specifies the length, in bytes, of the Content property.

__property int ContentLength = {read=GetIntegerVariable, write=SetIntegerVariable, index=0, nodefault};

Description

Set ContentLength to the length of the Content property, if it is known. If the length of the Content property is unknown, or if the response message does not include any content, set ContentLength to 0. Web clients use the ContentLength when reading the contents of the HTTP response message.

If the contents of the response message are taken from a stream, the value of ContentLength is set from the stream.


TWebResponse::ContentStream

TWebResponse	See also

Specifies stream object for writing the contents of the HTTP response message to the web client.

__property Classes::TStream* ContentStream = {read=FContentStream, write=SetContentStream};

Description

Use ContentStream to set the contents of the HTTP response message to a value that can be written from a stream. ContentStream allows the response object to write its contents directly from a stream.

The stream specified by ContentStream can access a string of HTML commands, the contents of a BLOB database field, or any MIME content type.

Note:	ContentStream supersedes the Content property. If both Content and ContentStream are set, the web client is sent the value of the ContentStream, not the value of the Content property.


TWebResponse::ContentType

TWebResponse	See also

Indicates the media type of the Content of the HTTP response message.

__property System::AnsiString ContentType = {read=GetStringVariable, write=SetStringVariable, index=8};

Description

Set ContentType to indicate the media type of the Content of the HTTP response message. The value of ContentType must specify a valid MIME content type. The ContentType string has the form Type/SubType.

For example, if the HTTP response message sends a string of HTML commands to the web client in response to a GET request, the ContentType is text/html.

Note:	If the HTTP request message includes an Accept header, ContentType should be one of the content types listed in the TWebRequest::Accept property.


TWebResponse::ContentVersion

TWebResponse	See also

Represents the version associated with the Content of the HTTP response message.

__property System::AnsiString ContentVersion = {read=GetStringVariable, write=SetStringVariable, index=9};

Description

Use ContentVersion to specify a version associated with the Content of the HTTP response. The meaning of ContentVersion depends on the type of information that is sent in the HTTP response. For example, if the Content of the HTTP response has a ContentType of text/html, ContentVersion would be the version of HTML used.

Server applications that introduce meanings for the ContentVersion property should document the interpretation they assign to ContentVersion.


TWebResponse::Cookies

TWebResponse	See also 	Example

Lists all cookie headers that should be sent with the response.

__property TCookieCollection* Cookies = {read=FCookies};

Description

Use Cookies to obtain direct access to the individual TCookie objects that represent the fields of the cookie headers in the response message. Each TCookie object represents in individual cookie header that is included with the response message.

Use the SetCookieField method to add cookie headers to this collection. SetCookieField creates and adds a new TCookie for a set of name/value pairs that share a common set of values for the domain, path, expires, and secure fields. Use the HeaderValue property of the individual entries in Cookies to determine the actual response header string that is sent for each cookie header.

Note:	For more information about the use of cookies, see the documentation on Netscape’s Web site.


TWebResponse::CustomHeaders

TWebResponse	See also

Lists message header strings that are added to the response message before it is sent.

__property Classes::TStrings* CustomHeaders = {read=FCustomHeaders, write=SetCustomHeaders};

Description

Use CustomHeaders to add header information to the response that can not be specified using the other properties of TWebResponse. Each string in the CustomHeaders property has the form HeaderName=Value, where HeaderName specifies the name of the header, and Value is the value for that header, formatted as a string.

Note:	Setting the CustomHeaders property assigns a set of strings to the custom headers list. It does not replace the TStrings object that is the value of CustomHeaders.


TWebResponse::Date

TWebResponse 	See also

Indicates the time and date when the HTTP response message is sent to the web client.

__property System::TDateTime Date = {read=GetDateVariable, write=SetDateVariable, index=0};

Description

Set Date to the current date and time immediately before sending the HTTP response message to the web client. Date is used by the web client to determine the age of the information returned.

Date is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TWebResponse::DerivedFrom

TWebResponse	See also

Specifies the URI of the resource where the Content of the HTTP response originated.

__property System::AnsiString DerivedFrom = {read=GetStringVariable, write=SetStringVariable, index=10};

Description

Set DerivedFrom to the URI where the value of Content originates. It is especially important to set DerivedFrom when the Content of the HTTP response did not originate from the resource indicated by the URL property of the request object.


TWebResponse::Expires

TWebResponse 	See also

Specifies the date and time after which the Content of the HTTP response message should be considered invalid.

__property System::TDateTime Expires = {read=GetDateVariable, write=SetDateVariable, index=1};

Description

Set Expires when the Content of the HTTP response message contains information that may become invalid with the passage of time. Setting an Expires value does not imply that the information or its source will necessarily change or cease to exist when the Expires date and time is reached. Web clients are simply warned to check the freshness of the information after the Expires date and time.

The value of Expires is specified in the local time of the machine. The HTTP response message translates this value to the date encoding used by HTTP.

Expires is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TWebResponse::HTTPRequest

TWebResponse	See also

Represents the HTTP request message for which this is a response.

__property TWebRequest* HTTPRequest = {read=FHTTPRequest};

Description

Read HTTPRequest to determine the header and contents of the HTTP request message that spawned this response message. The properties of HTTPRequest give access to the information sent in the web client request message.


TWebResponse::LastModified

TWebResponse 	See also

Indicates the date and time that the value of the Content property was last updated.

__property System::TDateTime LastModified = {read=GetDateVariable, write=SetDateVariable, index=2};

Description

Set LastModified to indicate the last time the Content of the response was modified. This allows web clients to determine whether their local version of that information is up-to-date. When the HTTP request is a HEAD message, this may allow the web client and server to skip a potentially expensive transfer of information.

The value of LastModified is specified in the local time of the machine. The HTTP response message translates this value to the date encoding used by HTTP.

LastModified is represented using the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since Dec. 30 1899. The fractional part of a TDateTime value is the fraction of a 24 hour day that has elapsed.


TWebResponse::Location

TWebResponse	See also

Specifies the URI of a resource the web client should point to for the completion of its request.

__property System::AnsiString Location = {read=GetStringVariable, write=SetStringVariable, index=6};

Description

Set Location when the TWebResponse created a new resource in response to the HTTP request message, or when servicing of the request must be delegated to another URI than the one specified in the HTTP request message.


TWebResponse::LogMessage

TWebResponse	See also

Describes the HTTP response message for event logging purposes.

__property System::AnsiString LogMessage = {read=GetLogMessage, write=SetLogMessage};

Description

Set LogMessage to a description of the action carried out by the TWebActionItem object that services this HTTP response. Usually, LogMessage includes the URI that handled the request message, along with date and time information.


TWebResponse::Realm

TWebResponse	See also

Specifies the set of protected-access URIs that includes the URL specified by the HTTP request message.

__property System::AnsiString Realm = {read=GetStringVariable, write=SetStringVariable, index=4};

Description

Set Realm when the response message returns 401 (Unauthorized) or 402 (Payment required). Realm is the name of a set of URIs that require a password or payment before the web client can access them. All the URIs in the realm, including the URL specified in the request message, are made available as soon as the web client provides the password or payment for the realm. The server application should keep track, internally, of the passwords or payments the client has provided, using the client information provided by the TWebRequest object.


TWebResponse::ReasonString

TWebResponse	See also

Indicates the status of the response to the web client request as a human-readable string.

__property System::AnsiString ReasonString = {read=GetStringVariable, write=SetStringVariable, index=1};

Description

Set ReasonString to inform the human web client of the success or failure of the HTTP request message. Each reason string is associated with a 3-digit status code whose value indicates the status of the response. The HTTP standard defines a number of stock status codes and corresponding reason strings. In addition, server applications can define new reason strings and associate them with unused status codes.


TWebResponse::Server

TWebResponse	See also

Provides information about the software used by the server application to handle the request.

__property System::AnsiString Server = {read=GetStringVariable, write=SetStringVariable, index=2};

Description

Set Server to a string giving the name and version number of the application that provides the Content of the response message. The value of Server can contain multiple product identifiers and comments, listed in order of significance and separated by spaces. Product identifiers take the form ProductName/VersionNumber.


TWebResponse::StatusCode

TWebResponse	See also

Indicates the status of the response to the HTTP request message as a 3-digit integer.

__property int StatusCode = {read=GetStatusCode, write=SetStatusCode, nodefault};

Description

Set StatusCode to inform the web client the status of the HTTP request message. Status codes are standard return values that can be interpreted by all web clients. Each status code has a corresponding reason string that provides a human web client with a more understandable indication of the status.

The following tables lists the standard status codes and their corresponding reason strings.

StatusCode	ReasonString

100	Continue

101	Switching Protocols

200	OK

201	Created

202	Accepted

203	Non-Authoritative Information

204	No Content

205	Reset Content

206	Partial Content

300	Multiple Choices

301	Moved Permanently

302	Moved Temporarily

303	See Other

304	Not Modified

305	Use Proxy

400	Bad Request

401	Unauthorized

402	Payment Required

403	Forbidden

404	Not Found

405	Method Not Allowed

406	Not Acceptable

407	Proxy Authentication Required

408	Request Time-out

409	Conflict

410	Gone

411	Length Required

412	Precondition Failed

413	Request Entity Too Large

414	Request-URI Too Large

415	Unsupported Media Type

500	Internal Server Error

501	Not Implemented

502	Bad Gateway

503	Service Unavailable

504	Gateway Time-out

505	HTTP Version not supported

Status codes not in the table can be created by the server application. When creating a new status code, the most significant digit should indicate the class of response, as follows:

•	1xx: Informational (request received, continuing process)

•	2xx: Success (request received, understood, and accepted)

•	3xx: Redirection (Further action needed to complete the request)

•	4xx: Client Error (request contains bad syntax or cannot be serviced)

•	5xx: Server Error (server failed to handle a valid request)


TWebResponse::Title

TWebResponse	See also

Specifies a title for the Content of the HTTP response message.

__property System::AnsiString Title = {read=GetStringVariable, write=SetStringVariable, index=11};

Description

Set the Title property to add a Title header to the HTTP response message. Title is an optional application-specific title associated with the information included in the message.


TWebResponse::Version

TWebResponse	See also

Specifies the HTTP protocol version number that the web client is using.

__property System::AnsiString Version = {read=GetStringVariable, write=SetStringVariable, index=0};

Description

Read Version to ensure that the properties set in the TWebResponse object will be understood by the web client. The value of Version is taken from the ProtocolVersion property of the TWebRequest object.

For more information on the different HTTP protocol versions, see the Internet standards documentation.


TWebResponse::WWWAuthenticate

TWebResponse	See also

Lists of one or more comma-separated challenges provided when the request fails with StatusCode 401 (Unauthorized).

__property System::AnsiString WWWAuthenticate = {read=GetStringVariable, write=SetStringVariable, index=3};

Description

Set WWWAuthenticate when the HTTP request fails because it requires access to a URI in a realm for which the web client has not provided a password. WWWAuthenticate consists of an authentication scheme name, followed by a comma-separated list of parameter/value pairs that specify the parameters to the authentication scheme. The first parameter/value pair indicates the realm.

For more information about HTTP authentication schemes, see the Internet standards documents.


TWebResponse methods

TWebResponse	Alphabetically	Legend

In TWebResponse

~TWebResponse

AddCustomHeaders

GetContent

GetCustomHeader

GetDateVariable

GetIntegerVariable

GetLogMessage

GetStatusCode

GetStringVariable

SendRedirect

SendResponse

SendStream

Sent

SetContent

SetContentStream

SetCookieField

SetCustomHeader

SetDateVariable

SetIntegerVariable

SetLogMessage

SetStatusCode

SetStringVariable

TWebResponse

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWebResponse methods

TWebResponse	By object	Legend

~TWebResponse

AddCustomHeaders

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetContent

GetCustomHeader

GetDateVariable

GetIntegerVariable

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLogMessage

GetStatusCode

GetStringVariable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

SendRedirect

SendResponse

SendStream

Sent

SetContent

SetContentStream

SetCookieField

SetCustomHeader

SetDateVariable

SetIntegerVariable

SetLogMessage

SetStatusCode

SetStringVariable

TWebResponse


TWebResponse::AddCustomHeaders

TWebResponse	See also

Appends the custom headers specified by the CustomHeaders property to the Headers parameter.

void __fastcall AddCustomHeaders(System::AnsiString &Headers);

Description

Call AddCustomHeaders to add the message headers described by the CustomHeaders property to a string of message headers. Each header is added on its own line (separated by carriage return and line feed), in the format HeaderName: Value.


TWebResponse::TWebResponse

TWebResponse	See also

Creates an instance of TWebResponse to represent the response to the HTTPRequest parameter.

__fastcall TWebResponse(TWebRequest* HTTPRequest);

Description

Applications shouldn’t need to call TWebResponse to instantiate a response object. The TWebApplication object creates a TWebResponse for each TWebRequest it creates.


TWebResponse::~TWebResponse

TWebResponse	See also

Destroys an instance of TWebResponse.

__fastcall virtual ~TWebResponse(void);

Description

Do not call ~TWebResponse. The TWebApplication object that creates the TWebResponse object destroys it.

~TWebResponse frees the ContentStream object if one was used to write the contents of the HTTP response message.


TWebResponse::GetContent

TWebResponse	See also

Provides the pure virtual prototype of a method to access the Content property.

virtual System::AnsiString __fastcall GetContent(void) = 0;

Description

Descendants of TWebResponse implement GetContent to provide an access method for their internal representation of the Content property. This method is pure virtual because response objects for different types of HTTP applications store the value of the Content property differently.


TWebResponse::GetCustomHeader

TWebResponse	See also

Returns the value of the custom header with the specified name.

System::AnsiString __fastcall GetCustomHeader(const System::AnsiString Name);

Description

Call GetCustomHeader to obtain the value of one of the custom headers specified in the CustomHeaders property. The Name parameter specifies the name of the HTTP message header.


TWebResponse::GetDateVariable

TWebResponse	See also

Provides the pure virtual prototype of a method to extract a date value from an indexed table of HTTP header variables.

virtual System::TDateTime __fastcall GetDateVariable(int Index) = 0;

Description

Descendants of TWebResponse implement GetDateVariable to provide a method by which date-time values are read from the internal table used to store HTTP header variables. The response object uses GetDateVariable to access the properties that represent dates.


TWebResponse::GetIntegerVariable

TWebResponse	See also

Provides the pure vitrual prototype of a method to extract an integer value from an indexed table of HTTP header variables.

virtual int __fastcall GetIntegerVariable(int Index) = 0;

Description

Descendants of TWebResponse implement GetIntegerVariable to provide a method by which integer values are read from the internal table used to store HTTP header variables. The response object uses GetIntegerVariable to access the properties that represent integers.


TWebResponse::GetLogMessage

TWebResponse	See also

Provides the pure virtual prototype of a method to access the LogMessage property.

virtual System::AnsiString __fastcall GetLogMessage(void) = 0;

Description

Descendants of TWebResponse implement GetLogMessage to provide an access method for internal representation of the LogMessage property. This method is pure virtual because response objects for different types of HTTP applications store the value of the LogMessage property differently.


TWebResponse::GetStatusCode

TWebResponse	See also

Provides the pure virtual prototype of a method to access the StatusCode property.

virtual int __fastcall GetStatusCode(void) = 0;

Description

Descendants of TWebResponse implement GetStatusCode to provide an access method for internal representation of the StatusCode property. This method is pure virtual because response objects for different types of HTTP applications store the value of the StatusCode property differently.


TWebResponse::GetStringVariable

TWebResponse	See also

Provides the pure virtual prototype of a method to extract a string value from an indexed table of HTTP header variables.

virtual System::AnsiString __fastcall GetStringVariable(int Index) = 0;

Description

Descendants of TWebResponse implement GetStringVariable to provide a method by which the string values are read from the internal table used to store HTTP header variables. The response object uses GetStringVariable to access the properties that represent strings.


TWebResponse::SendRedirect

TWebResponse	See also

Provides the pure virtual prototype of a method that sends the response with a StatusCode of 301 (Moved Permanently) and a Location of URI.

virtual void __fastcall SendRedirect(const System::AnsiString URI) = 0;

Description

Call SendRedirect to redirect the web client request to another URI that is the proper target of the request. SendRedirect does the same thing as setting the StatusCode to 301, the Location to URI, and calling SendResponse.


TWebResponse::SendResponse

TWebResponse	See also

Provides the pure virtual prototype of a method that sends the HTTP response message to the web client.

virtual void __fastcall SendResponse(void) = 0;

Description

Call SendResponse after setting the properties of the HTTP response object to specify the response that should be made to the web client. If the request should be redirected to another URI, it is more efficient to call SendRedirect instead.


TWebResponse::SendStream

TWebResponse	See also

Provides the pure virtual prototype of a method that sends the HTTP response message with the contents set to the contents of AStream.

virtual void __fastcall SendStream(Classes::TStream* AStream) = 0;

Description

Only call SendStream after first calling SendResponse. Unlike SendStream, SendResponse fills the header of the HTTP response message, based on the properties of the TWebResponse object. If SendResponse has not been called first to set the header of the HTTP response message, set the ContentStream property to AStream, and call SendResponse.


TWebResponse::Sent

TWebResponse	See also

Indicates whether the HTTP response message has already been sent.

virtual bool __fastcall Sent(void);

Description

Because SendRedirect and SendStream are pure virtual methods for TWebResponse, TWebResponse::Sent always returns false. Descendants of TWebResponse override Sent to check whether the message was sent and return true or false as appropriate.

TWebApplication objects read Sent and send unsent responses to the web client.


TWebResponse::SetContent

TWebResponse	See also

Provides the pure virtual prototype of a method to set the Content property.

virtual void __fastcall SetContent(const System::AnsiString Value) = 0;

Description

Descendants of TWebResponse implement SetContent to provide a method for setting the Content property. This method is pure virtual because response objects for different types of HTTP applications can store the value of the Content property differently.


TWebResponse::SetContentStream

TWebResponse	See also

Sets the value of the ContentStream property to the Value parameter.

virtual void __fastcall SetContentStream(Classes::TStream* Value);

Description

SetContentStream frees the previous value of ContentStream and replaces the property with the Value parameter.


TWebResponse::SetCookieField

TWebResponse	See also

Adds a cookie header to the response message.

void __fastcall SetCookieField(Classes::TStrings* Values, const System::AnsiString ADomain, const System::AnsiString APath, System::TDateTime AExpires, bool ASecure);

Description

Call SetCookieField to add a cookie header to the Cookies property. Each cookie header contains a set of name/value pairs that can be passed on by the client application. Use the Values parameter to specify the name/value pairs as strings of the form Name=Value. Use the ADomain and APath parameters to indicate which URLs the cookie should be sent to. Use the AExpires parameter to indicate when the cookie is no longer valid. Use the ASecure property to indicate whether the cookie should only be passed on by the client if a secure connection is used.

See the documentation on the Netscape Web site for more information about cookies.


TWebResponse::SetCustomHeader

TWebResponse	See also

Replaces the value of a specified custom header.

void __fastcall SetCustomHeader(const System::AnsiString Name, const System::AnsiString Value);

Description

Call SetCustomHeader to add a new custom header to the list maintained by the CustomHeaders property, or to change the value of one of the headers already in the list. SetCustomHeader locates the header in the list with the name specified by the Name parameter. If a header with that name is in the list, SetCustomHeader replaces the value of that header with the value specified as the Value parameter. If the name was not found, SetCustomHeader adds a new header to the list with the given name and value.


TWebResponse::SetDateVariable

TWebResponse	See also

Provides the pure virtual prototype of a method to set a date-time valued HTTP header property.

virtual void __fastcall SetDateVariable(int Index, const System::TDateTime Value) = 0;

Description

Descendants of TWebResponse implement SetDateVariable to provide a method by which date-time values are written to the internal table used to store HTTP header variables. The response object uses SetDateVariable to set the properties that represent dates.


TWebResponse::SetIntegerVariable

TWebResponse	See also

Provides the pure virtual prototype of a method to set an integer valued HTTP header property.

virtual void __fastcall SetIntegerVariable(int Index, int Value) = 0;

Description

Descendants of TWebResponse implement SetIntegerVariable to provide a method by which integer values are written to the internal table used to store HTTP header variables. The response object uses SetIntegerVariable to set the properties that represent integers.


TWebResponse::SetLogMessage

TWebResponse	See also

Provides the pure virtual prototype of a method to set the value of the LogMessage property.

virtual void __fastcall SetLogMessage(const System::AnsiString Value) = 0;

Description

Descendants of TWebResponse implement SetLogMessage to provide a method to set the internal representation of the LogMessage property. This method is pure virtual because response objects for different types of HTTP applications store the value of the LogMessage property differently.


TWebResponse::SetStatusCode

TWebResponse	See also

Provides the pure virtual prototype of a method to set the value of the StatusCode property.

virtual void __fastcall SetStatusCode(int Value) = 0;

Description

Descendants of TWebResponse implement SetStatusCode to provide a method to set the internal representation of the StatusCode property. This method is pure virtual because response objects for different types of HTTP applications store the value of the StatusCode property differently.


TWebResponse::SetStringVariable

TWebResponse	See also

Provides the pure virtual prototype of a method to set a string valued HTTP header property.

virtual void __fastcall SetStringVariable(int Index, const System::AnsiString Value) = 0;

Description

Descendants of TWebResponse implement SetStringVariable to provide a method by which string values are written to the internal table used to store HTTP header variables. The response object uses SetStringVariable to set the properties that represent strings.


Accessibility

Read-only


Scope

Protected


Hierarchy

TObject


 TRichEdit

Hierarchy	Properties	Methods	Events	See also

TRichEdit is a wrapper for a Windows rich text edit control.

Unit

comctrls

Description

Use a TRichEdit object to put a standard Windows rich text edit control on a form. Rich text edit controls let the user enter text that includes variation in font attributes and paragraph formatting information.

TRichEdit provides the properties and methods to enter and work with rich text. TRichEdit does not provide any user interface components to make these formatting options available to the user. Applications must implement the user interface components to surface the rich text capabilities of a TRichEdit object.

TRichEdit publishes many of the properties inherited from TCustomRichEdit, but does not introduce any new behavior.


TRichEdit properties

TRichEdit	Alphabetically	Legend

Derived from TCustomRichEdit

DefAttributes

DefaultConverter

HideScrollBars

HideSelection

Lines

PageRect

Paragraph

PlainText

SelAttributes

SelLength

SelStart

SelText

Derived from TCustomMemo

Alignment

CaretPos

ScrollBars

WantReturns

WantTabs

WordWrap

Derived from TCustomEdit

BorderStyle

CanUndo

MaxLength

Modified

ReadOnly

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Text

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TRichEdit properties

TRichEdit	By object	Legend

Align

Alignment

BoundsRect

CanUndo

CaretPos

DefaultConverter

BorderStyle

Brush

ClientOrigin

ClientHeight

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DefAttributes

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

HideScrollBars

HideSelection

Hint

ImeMode

ImeName

Left

Lines

MaxLength

Modified

Name

Owner

PageRect

Paragraph

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PlainText

PopupMenu

ReadOnly

ScrollBars

SelAttributes

SelLength

SelStart

SelText

ShowHint

Showing

TabOrder

TabStop

Tag

Text

Top

VCLComObject

Visible

WantReturns

WantTabs

Width

WindowProc

WordWrap


TRichEdit events

TRichEdit	Alphabetically	Legend

Derived from TCustomRichEdit

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange

Derived from TCustomEdit

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TRichEdit events

TRichEdit	By object	Legend

OnChange

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange

OnStartDrag


TRichEdit methods

TRichEdit	Alphabetically

In TRichEdit

~TRichEdit

TRichEdit

Derived from TCustomRichEdit

Clear

FindText

GetSelTextBuf

Print

RegisterConversionFormat

Derived from TCustomEdit

ClearSelection

ClearUndo

CopyToClipboard

CutToClipboard

PasteFromClipboard

SelectAll

SetSelTextBuf

Undo

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TRichEdit methods

TRichEdit	By object

~TRichEdit

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

ClearSelection

ClearUndo

ClientToScreen

ContainsControl

ControlAtPos

CopyToClipboard

CutToClipboard

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

FindText

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetSelTextBuf

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

PasteFromClipboard

Perform

Print

Realign

Refresh

RegisterConversionFormat

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SelectAll

SendToBack

SetBounds

SetFocus

SetSelTextBuf

SetTextBuf

Show

TRichEdit

Undo

Update

UpdateControlState


TRichEdit::TRichEdit

TRichEdit

Creates a new TRichEdit object.

__fastcall virtual TRichEdit(Classes::TComponent* AOwner) : Comctrls::TCustomRichEdit(AOwner) { }

Description

Do not call TRichEdit directly when creating a rich edit control at runtime. Instead, use the keyword new, which returns an indirect reference to the newly created rich edit control. Rich edit controls placed in a form at design time are created automatically.

Pass a single Component as a parameter to provide the rich edit control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the rich edit control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TRichEdit::~TRichEdit

TRichEdit

Frees the memory associated with the TRichEdit object.

__fastcall virtual ~TRichEdit(void) { }

Description

Do not call ~TRichEdit directly. Instead, use the delete keyword on the object, which causes ~TRichEdit to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomEdit

TCustomMemo

TCustomRichEdit


TResourceStream

Hierarchy	Properties	Methods	See also

TResourceStream is a memory stream that provides access to the compiled resources in a Windows application.

Unit

classes

Description

Use TResourceStream to read the resources of a Windows application. An instance of TResourceStream holds the value of a single resource in a memory buffer where it is accessible to the application.

The global ReadComponentRes function uses TResourceStream to access the compiled resources used by the application.


TResourceStream properties

TResourceStream	Alphabetically	Legend

Derived from TCustomMemoryStream

Memory

Derived from TStream

Position

Size


TResourceStream properties

TResourceStream	By object	Legend

Position

Size

Memory


TResourceStream methods

TResourceStream	Alphabetically

In TResourceStream

~TResourceStream

TResourceStream

Write

Derived from TCustomMemoryStream

Read

SaveToFile

SaveToStream

Seek

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TResourceStream methods

TResourceStream	By object

~TResourceStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

SaveToFile

SaveToStream

Seek

TResourceStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TResourceStream::TResourceStream

TResourceStream	See also

Creates an instance of TResourceStream associated with a particular resource name or ID and type.

__fastcall TResourceStream(int Instance, const System::AnsiString ResName, char * ResType);

__fastcall TResourceStream(int Instance, int ResID, char * ResType);

Description

Do not call TResourceStream directly to instantiate a TResourceStream. Instead, use the new keyword, passing in parameters that identify the resource in a specified instance. TResourceStream finds the resource data and loads it into the Memory buffer for the TResourceStream.

The Instance parameter is the Windows instance handle associated with the executable or DLL that contains the resource.

In the first constructor syntax, the ResName is the string associated with the resource in the .RC file that was compiled with the application. If the resource is associated with an integer ID rather than a string, use the string representation of the integer after a pound sign (#), or use the second constructor syntax. Thus, for example, a resource with an integer identifier of 128 be identified by a ResName of “#128” when invoking the first constructor syntax, or by a ResID of 128 when invoking the second constructor syntax.

Note:	Specifying resources by ID requires less memory than specifying resources by name.

The ResType is a string identifying the type of the resource. Applications can define their own resource types and identify them by name in the ::RC file. In addition, Windows provides a number of predefined resource types. To identify a resource that is one of the predefined Windows resource types, set ResType to the appropriate value from the following table.

ResType	Type of resource

RT_ACCELERATOR	Accelerator table

RT_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource


TResourceStream::~TResourceStream

TResourceStream	See also

Destroys an instance of TResourceStream.

__fastcall virtual ~TResourceStream(void);

Description

Do not call ~TResourceStream directly in an application to destroy an instance of TResourceStream. Instead, use the delete keyword.

~TResourceStream frees the memory buffer that stores the resource before calling the parent object’s destructor.


TResourceStream::Write

TResourceStream	See also

Overrides the inherited method to throw an exception when an attempt is made to write the resource back to the application.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Applications should not use a TResourceStream to write the resources of the running application. Write overrides the parent class’s method to throw an EStreamError exception when an application tries to write to the application’s resources.

As all other data-writing methods of TResourceStream (WriteBuffer, WriteComponent) call Write to do the actual writing, calling any of the data-writing methods of TResourceStream will throw an exception.


Accessibility

Read-only


Hierarchy

TObject

TStream

TCustomMemoryStream


 TSaveDialog

Hierarchy	Properties	Methods	Events	See also

TSaveDialog displays a Save As dialog for saving files.

Unit

dialogs

Description

TSaveDialog displays a modal Windows dialog box for selecting file names and saving files. The dialog does not appear at runtime until it is activated by a call to the Execute method. When the user clicks Save, the dialog closes and the selected file name is stored in the FileName property.


TSaveDialog properties

TSaveDialog	Alphabetically	Legend

Derived from TOpenDialog

DefaultExt

FileEditStyle

FileName

Files

Filter

FilterIndex

HistoryList

InitialDir

Options

Title

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TSaveDialog properties

TSaveDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

Ctl3D

DefaultExt

DesignInfo

FileEditStyle

FileName

Files

FilterIndex

Filter

HelpContext

HistoryList

InitialDir

Name

Options

Owner

Tag

Title

VCLComObject


TSaveDialog events

TSaveDialog	Alphabetically	Legend

Derived from TOpenDialog

OnCanClose

OnSelectionChange

Derived from TCommonDialog

OnClose

OnShow


TSaveDialog events

TSaveDialog	By object	Legend

OnCanClose

OnClose

OnSelectionChange

OnShow


TSaveDialog methods

TSaveDialog	Alphabetically	Legend

In TSaveDialog

~TSaveDialog

Execute

TSaveDialog

Derived from TOpenDialog

GetStaticRect

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSaveDialog methods

TSaveDialog	By object	Legend

~TSaveDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetStaticRect

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TSaveDialog


TSaveDialog::Execute

TSaveDialog

Execute displays the Save As dialog box.

virtual bool __fastcall Execute(void);

Description

Execute opens the Save As dialog, returning true when the user selects a file name and clicks Save.


TSaveDialog::TSaveDialog

TSaveDialog

TSaveDialog creates a new TSaveDialog object.

__fastcall virtual TSaveDialog(Classes::TComponent* AOwner) : Dialogs::TOpenDialog(AOwner) { }

Description

Do not call TSaveDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.


TSaveDialog::~TSaveDialog

TSaveDialog

~TSaveDialog frees the memory associated with the TSaveDialog object.

__fastcall virtual ~TSaveDialog(void) { }

Description

Do not call ~TSaveDialog directly. Instead, use the delete keyword on the object, which causes ~TSaveDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog

TOpenDialog


TSaveDialog example

TSaveDialog


 TSavePictureDialog

Hierarchy	Properties	Methods	Events	See also

TSavePictureDialog displays a Save As dialog for saving graphics files.

Unit

extdlgs

Description

TSavePictureDialog displays a modal Windows dialog box for selecting file names and saving graphics files. This component is just like TSaveDialog, except that it includes a rectangular preview region. If the selected image can be read by TPicture, it is displayed in the preview region; supported file types include bitmap (.BMP), icon (.ICO), Windows metafile (.WMF), and enhanced Windows metafile (.EMF). If the selected image cannot be displayed, “(None)” appears in the preview region.


TSavePictureDialog properties

TSavePictureDialog	Alphabetically	Legend

Derived from TOpenDialog

DefaultExt

FileEditStyle

FileName

Files

Filter

FilterIndex

HistoryList

InitialDir

Options

Title

Derived from TCommonDialog

Ctl3D

HelpContext

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TSavePictureDialog properties

TSavePictureDialog	By object	Legend

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

Ctl3D

DefaultExt

DesignInfo

FileEditStyle

FileName

Files

FilterIndex

Filter

HelpContext

HistoryList

InitialDir

Name

Options

Owner

Tag

Title

VCLComObject


TSavePictureDialog events

TSavePictureDialog	Alphabetically	Legend

Derived from TOpenDialog

OnCanClose

OnSelectionChange

Derived from TCommonDialog

OnClose

OnShow


TSavePictureDialog events

TSavePictureDialog	By object	Legend

OnCanClose

OnClose

OnSelectionChange

OnShow


TSavePictureDialog methods

TSavePictureDialog	Alphabetically

In TSavePictureDialog

~TSavePictureDialog

Execute

TSavePictureDialog

Derived from TOpenPictureDialog

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSavePictureDialog methods

TSavePictureDialog	By object

~TSavePictureDialog

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

Execute

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TSavePictureDialog


TSavePictureDialog::Execute

TSavePictureDialog

Execute displays the Save As dialog box.

virtual bool __fastcall Execute(void);

Description

Execute opens the Save As dialog, returning true when the user selects a file name and clicks Save.


TSavePictureDialog::TSavePictureDialog

TSavePictureDialog

TSavePictureDialog creates a new TSavePictureDialog object.

__fastcall virtual TSavePictureDialog(Classes::TComponent* AOwner) : Extdlgs::TOpenPictureDialog(AOwner) { }

Description

Do not call TSavePictureDialog directly. Instead, use the keyword new, which returns an indirect reference to the new dialog.


TSavePictureDialog::~TSavePictureDialog

TSavePictureDialog

~TSavePictureDialog frees the memory associated with the TSavePictureDialog object.

__fastcall virtual ~TSavePictureDialog(void) { }

Description

Do not call ~TSavePictureDialog directly. Instead, use the delete keyword on the object, which causes ~TSavePictureDialog to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TCommonDialog

TOpenDialog

TOpenPictureDialog


TSavePictureDialog example

TSavePictureDialog


TScreen

Hierarchy	Properties	Methods	Events	See also

TScreen represents the state of the screen in which an application runs.

Unit

forms

Description

TScreen introduces properties that keep track of

•	What forms and data modules have been instantiated by the application.

•	The active form, and the active control within that form.

•	The size and resolution of the screen.

•	The cursors and fonts available for the application to use.

There is a global variable, Screen, of type TScreen, that is already instantiated for use by C++Builder applications. Use Screen to obtain information about the current state of the screen in an application.


TScreen properties

TScreen	Alphabetically	Legend

In TScreen

ActiveControl

ActiveCustomForm

ActiveForm

Cursor

Cursors

CustomFormCount

CustomForms

DataModuleCount

DataModules

DefaultIme

DefaultKbLayout

Fonts

FormCount

Forms

Height

IconFont

Imes

PixelsPerInch

Width

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TScreen properties

TScreen	By object	Legend

ActiveControl

ActiveCustomForm

ActiveForm

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Cursor

Cursors

CustomFormCount

CustomForms

DataModuleCount

DataModules

DefaultIme

DefaultKbLayout

DesignInfo

Fonts

FormCount

Forms

Height

IconFont

Imes

Name

Owner

PixelsPerInch

Tag

VCLComObject

Width


TScreen::ActiveControl

TScreen	See also

Indicates which control currently has input focus on the screen.

__property Controls::TWinControl* ActiveControl = {read=FActiveControl};

Description

Read ActiveControl to learn which windowed control object in the active form currently receives the input from the keyboard.

ActiveControl is a read-only property. To change the ActiveControl, use the SetFocusedControl method of the form which contains control that should receive focus.

After focus shifts from one control to another, the screen receives an OnActiveControlChange event.


TScreen::ActiveCustomForm

TScreen	See also

Indicates the descendant of TCustomForm that currently has focus.

__property TCustomForm* ActiveCustomForm = {read=FActiveCustomForm};

Description

Read ActiveForm to learn which form or property page has input focus. If the active custom form is a TForm object, ActiveCustomForm is the same as ActiveForm.


TScreen::ActiveForm

TScreen	See also 	Example

Indicates which form currently has focus.

__property TForm* ActiveForm = {read=FActiveForm};

Description

Read ActiveForm to learn which form in the application has input focus. If the application is not currently active, ActiveForm is the form that will have focus when the application becomes active again.

ActiveForm is a read-only property. To change the ActiveForm, use the SetFocus method of the form that should receive focus. ActiveForm will also change if the SetFocusedControl method of an inactive form is called to set focus to a control on that inactive form.

After focus shifts from one form to another, the screen receives an OnActiveFormChange event.


TScreen::Cursor

TScreen	See also 	Example

Controls the mouse cursor image on a global level.

__property Controls::TCursor Cursor = {read=FCursor, write=SetCursor, nodefault};

Description

Set Cursor to override the cursor image associated with individual control objects. When Cursor is crDefault, the individual objects determine the cursor image. Assigning any other value sets the mouse cursor image for all windows belonging to the application. The global mouse cursor image remains in effect until the screen’s Cursor property is changed back to crDefault.

Cursor can be set to any of the cursor values available in the Cursors property. This can be one of the built-in cursor values, or a custom cursor that has been added to the Cursors property.


TScreen::Cursors

TScreen	See also 	Example

Lists the cursors available to the application.

__property HICON Cursors[int Index] = {read=GetCursors, write=SetCursors};

Description

Use Cursor to access a particular cursor for use by the application or by a control within the application. TScreen includes several built-in cursors that are indexed by symbolic cursor constants. The image associated with the built-in cursors constants can be changed by setting the Cursors property.

These are the cursor constants and their position in the Cursors property array

Constant	Value	Image

crDefault	0	depends on the ActiveControl.

crNone	-1

crArrow	 -2

crCross	-3

crIBeam	-4

crSize	-5

crSizeNESW	-6

crSizeNS	-7

crSizeNWSE	-8

crSizeWE	-9

crUpArrow	-10

crHourGlass	-11

crDrag	-12

crNoDrop	-13

crHSplit	-14

crVSplit	-15

crMultiDrag	-16

crSQLWait	-17

crNo	-18

crAppStart	-19

crHelp	-20

crHandPoint	-21

Custom cursors can be added to the Cursors property for use by the application or any of its controls. To add a custom cursor to an application:

1	Create the cursor resource using a resource editor.

2	Declare a cursor constant with a value that does not conflict with an existing cursor constant.

3	Use the Windows API function LoadCursor to obtain a handle to the new cursor.

4	Set the Cursors property, indexed by the newly declared cursor constant, to the handle obtained from LoadCursor.

Note:	Don’t call the Windows API function DestroyCursor when finished with a custom cursor; C++Builder does this automatically.


TScreen::CustomFormCount

TScreen	See also

Indicates the number of forms or property pages displayed on the screen.

__property int CustomFormCount = {read=GetCustomFormCount, nodefault};

Description

Read CustomFormCount to learn the number of forms or property pages currently displayed on the screen. These forms can be accessed by the CustomForms property. CustomFormCount can be used with CustomForms to iterate over all the forms and property pages in an application.


TScreen::CustomForms

TScreen	See also 	Example

Lists all the forms and property pages that are currently displayed in the application.

__property TCustomForm* CustomForms[int Index] = {read=GetCustomForms};

Description

Use CustomForms to access a form or property page by index. The value of Index is a number between zero (the first custom form) and CustomFormCount - 1. CustomForms can be used with CustomFormCount when an application needs to iterate over all its forms and property pages.


TScreen::DataModuleCount

TScreen	See also

Indicates the number of data modules that are currently instantiated in the application.

__property int DataModuleCount = {read=GetDataModuleCount, nodefault};

Description

Read DataModuleCount to learn the number of data modules in the DataModules property. DataModuleCount can be used with DataModules when an application needs to iterate over all its data modules.


TScreen::DataModules

TScreen	See also

Lists all the data modules that are currently instantiated in the application.

__property TDataModule* DataModules[int Index] = {read=GetDataModule};

Description

Use DataModules to access an instantiated data module by index. The value of Index is a number between zero (the first data module) and DataModuleCount - 1. DataModules can be used with DataModuleCount when an application needs to iterate over all its data modules.


TScreen::DefaultIme

TScreen	See also

Indicates which input method editor (IME) is active when the TScreen object is created.

__property System::AnsiString DefaultIme = {read=FDefaultIme};

Description

In applications that support asian language characters, read DefaultIme to determine the IME that is active when the application starts.

An IME is a front-end input processor for asian language characters. The IME hooks all keyboard input, converts it to asian characters in a conversion window, and sends the converted characters or strings on to the C++Builder application. There can be multiple IMEs installed on a single system. They vary in user interface, conversion dictionaries, and input method.

Individual controls can override the default IME. When a control specifies a different IME should be used to enter information into the control, the IME that processes keyboard input changes when the control has focus. When the control loses focus, DefaultIme is restored as the system IME.


TScreen::DefaultKbLayout

TScreen	See also

Indicates the Windows handle to the keyboard layout that was active when the application started running.

__property HKL DefaultKbLayout = {read=FDefaultKbLayout, nodefault};

Description

Use DefaultKbLayout for making Windows API calls that require a handle to a keyboard layout. For example, if an application changes the keyboard layout to match the settings for another country, the value of DefaultKbLayout can be used as a parameter to the Windows ActivateKeyboardLayout function in order to restore the original layout.

For asian keyboards, the keyboard layout identifies the input method editor (IME) as well as the default language. Use DefaultKbLayout in Windows API calls that work with the IME. DefaultKbLayout is the keyboard layout handle associated with the IME named by the DefaultIme property.


TScreen::Fonts

TScreen	See also 	Example

Lists the face names for all fonts supported by the screen.

__property Classes::TStrings* Fonts = {read=FFonts};

Description

Read Fonts to learn what screen fonts are currently installed. Applications can use Fonts to ensure that they do not request a font that is not installed on the user’s system. When an application uses a TFont object to request a font that is not installed, Windows substitutes another font, which may not be a font appropriate to the application’s needs.

Note:	Fonts is a list of screen fonts. It does not give any indication of the printer fonts available to the application.


TScreen::FormCount

TScreen	See also 	Example

Indicates the number of forms displayed on the screen.

__property int FormCount = {read=GetFormCount, nodefault};

Description

Read FormCount to learn the number of forms currently displayed on the screen. These forms can be accessed by the Forms property. FormCount can be used with Forms to iterate over all the forms in an application.


TScreen::Forms

TScreen	See also 	Example

Lists all the forms currently displayed in the application.

__property TForm* Forms[int Index] = {read=GetForm};

Description

Use Forms to access a form by index. The value of Index is a number between zero (the first form) and FormCount - 1. Forms can be used with FormCount when an application needs to iterate over all its forms, including all dialogs.


TScreen::Height

TScreen	See also 	Example

Indicates the vertical size of the screen in pixels.

__property int Height = {read=GetHeight, nodefault};

Description

Read Height to learn the size of the user’s screen in pixels. The size or position of objects placed on the screen, can then be set to ensure that the objects fit on screen and don’t look crowded.


TScreen::IconFont

TScreen	See also

Specifies the font used to display the labels on the icons in file selection dialogs.

__property Graphics::TFont* IconFont = {read=FIconFont, write=FIconFont};

Description

IconFont stores the Windows 95 icon font setting. This font is used to label the icons on the Windows desktop, and icons in the file selection dialogs.


TScreen::Imes

TScreen	See also

Lists all input method editors (IMEs) installed on the system.

__property Classes::TStrings* Imes = {read=FImes};

Description

Read Imes to obtain a list of all IMEs that are listed in the Windows registry. An IME is a front-end input processor for asian language characters. The IME hooks all keyboard input, converts it to asian characters in a conversion window, and sends the converted characters or strings on to the C++Builder application. IMEs vary in user interface, conversion dictionaries, and input method.

Individual controls can require a specific IME to process the keyboard input when they have focus. To specify an IME, the control sets its ImeName property to one of the strings in Imes.

Each IME name in Imes has an associated keyboard layout handle. A keyboard layout handle is a Windows handle that identifies the primary language and IME used to process keyboard input. Use the keyboard layout handle in Windows API calls for programming the IME. To get the keyboard layout handle for a particular IME, a control can use code such as the following:

HKeyboard = Screen->Imes->Objects(Screen->Imes->IndexOf(ImeName));


TScreen::PixelsPerInch

TScreen	See also

Indicates the number of screen pixels that make up a logical inch in the vertical direction.

__property int PixelsPerInch = {read=FPixelsPerInch, nodefault};

Description

Read PixelsPerInch to convert between measurements in pixels and measurements in logical inches. PixelsPerInch is only accurate for vertical measurements. Most screens have a different scaling factor for horizontal measurements. The value in PixelsPerInch is set from Windows when C++Builder loads.


TScreen::Width

TScreen	See also 	Example

Indicates the horizontal size of the screen in pixels.

__property int Width = {read=GetWidth, nodefault};

Description

Read Width to learn the size of the user’s screen in pixels. The size or position of objects placed on the screen, can then be set to ensure that the objects fit on screen and don’t look crowded.


TScreen events

TScreen	Alphabetically

In TScreen

OnActiveControlChange

OnActiveFormChange


TScreen events

TScreen	By object

OnActiveControlChange

OnActiveFormChange


TScreen::OnActiveControlChange

TScreen	See also 	Example

Occurs immediately after input focus changes to a new windowed control.

__property Classes::TNotifyEvent OnActiveControlChange = {read=FOnActiveControlChange, write=FOnActiveControlChange};

Description

Write an OnActiveControlChange event handler to take specific action when input focus changes to a new control. The change in focus may be within the active form, or across forms to a new form that then becomes the active form.

When focus moves from one control to another, the following events occur.

1	If the new focused control is in a different form, focus moves to the new form.

2	Focus moves to the new active control.

3	If the active form changed, an OnActiveFormChange event occurs.

4	An OnActiveControlChange event occurs.


TScreen::OnActiveFormChange

TScreen	See also 	Example

Occurs immediately after a new form becomes active in a multi-form application.

__property Classes::TNotifyEvent OnActiveFormChange = {read=FOnActiveFormChange, write=FOnActiveFormChange};

Description

Write an OnActiveFormChange event handler to take specific action when a new form becomes active. OnActiveFormChange occurs when the active form for the application changes, not when a form becomes active because the application becomes active.


TScreen methods

TScreen	Alphabetically

In TScreen

~TScreen

TScreen

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TScreen methods

TScreen	By object

~TScreen

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TScreen


TScreen::TScreen

TScreen	See also

Creates an instance of TScreen.

__fastcall virtual TScreen(Classes::TComponent* AOwner);

Description

Do not create separate instances of TScreen. There is a global variable, Screen, of type TScreen, that is already instantiated for use by C++Builder applications. The properties of Screen are global to the entire application.

TScreen allocates memory for the TScreen object and

•	Fills the Cursors property with the built-in cursors.

•	Fills the Fonts property with the available screen fonts.

•	Fills the Imes property will all registered input method editors (IMEs), and sets the DefaultIme and DefaultKbLayout properties.

•	Sets the PixelsPerInch property for the current screen resolution.

•	Creates helper objects for the IconFont, Forms and DataModules properties.


TScreen::~TScreen

TScreen	See also

Destroys an instance of TScreen.

__fastcall virtual ~TScreen(void);

Description

Do not destroy the global object Screen that is automatically instantiated in C++Builder applications. Screen is used by many C++Builder objects.

~TScreen frees the memory associated with the DataModules, Forms, Fonts, IconFont and Imes properties, and releases the cursors used by the Cursors property.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent


 TScrollBar

Hierarchy	Properties	Methods	Events	See also

TScrollBar is a Windows scroll bar, which is used to scroll the contents of a window, form, or control.

Unit

stdctrls

Description

Use TScrollBar to add a free-standing scrollbar to a form. Many controls have properties that add scroll bars which are an integral part of the control. TScrollBar allows controls that do not have integrated scroll bars or groupings of controls to be scrolled when the user manipulates the TScrollBar object.


TScrollBar properties

TScrollBar	Alphabetically	Legend

In TScrollBar

Kind

LargeChange

Max

Min

PageSize

Position

SmallChange

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TScrollBar properties

TScrollBar	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Handle

Height

HelpContext

Hint

Kind

LargeChange

Left

Max

Min

Name

Owner

PageSize

Parent

ParentCtl3D

ParentShowHint

ParentWindow

PopupMenu

Position

ShowHint

Showing

SmallChange

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TScrollBar::Kind

TScrollBar 	Example

Specifies whether the scroll bar is horizontal or vertical.

__property Forms::TScrollBarKind Kind = {read=FKind, write=SetKind, default=0};

Description

Set Kind to indicate the orientation of the scrollbar. These are the possible values:

Value	Meaning

sbHorizontal	Scroll bar is horizontal

sbVertical	Scroll bar is vertical


TScrollBar::LargeChange

TScrollBar	See also 	Example

Determines how much Position changes when the user clicks the scroll bar on either side of the thumb tab or presses PgUp or PgDn.

__property Forms::TScrollBarInc LargeChange = {read=FLargeChange, write=FLargeChange, default=1};

Description

Set LargeChange to specify how much to change the value of Position when the user clicks on the side of the thumb tab (that is, on the thumb tab track, but not on the thumb tab itself). The Max and Min properties define the total range over which Position can vary.

For example, if Max is 30000 and Min is 0, the scroll box can assume 30,000 positions. If the LargeChange property setting is 10000 and the Position property is 0, the user can click the scroll bar track three times after the thumb tab before it moves all the way to the end of the scroll bar (30000 / 10000 = 3).

LargeChange should correspond to the portion of this range that the user sees in one page or screen, expressed in the logical units used by the Max, Min, and Position properties.


TScrollBar.Max
TScrollBar::Max

TScrollBar	See also 	Example

Specifies the maximum position represented by the scrollbar.

__property int Max = {read=FMax, write=SetMax, default=100};

Description

Set Max to the maximum value the Position property can take. The Max and Min properties define the total range over which Position can vary.


TScrollBar.Min
TScrollBar::Min

TScrollBar	See also 	Example

Specifies the minimum position represented by the scrollbar.

__property int Min = {read=FMin, write=SetMin, default=0};

Description

Set Min to the minimum value the Position property can take. The Min and Max properties define the total range over which Position can vary.


TScrollBar::PageSize

TScrollBar	See also

Specifies amount of thumb tab track bar represents a single view.

__property int PageSize = {read=FPageSize, write=SetPageSize, nodefault};

Description

Set PageSize to the distance along the track bar that corresponds to a single view. The current Position is marked by thumb tab. The PageUp key decrements the value of Position by PageSize, and PageDown key increments the value of Position by PageSize.


TScrollBar::Position

TScrollBar	See also 	Example

Indicates the current position of the scrollbar.

__property int Position = {read=FPosition, write=SetPosition, default=0};

Description

Read Position to determine the current position of the thumb tab. This value can be used to determine how to scroll any components controlled by the scroll bar. When the user scrolls the scroll bar, the value of Position changes. Set Position to programmatically move the thumb tab of the scroll bar.

The number of possible positions on the scroll bar is determined by the difference between the Max property and the Min property. If Position has the same value as Min, the thumb tab appears at the far left of a horizontal scroll bar or the top of a vertical scroll bar. If Position has the same value as Max, the thumb tab appears at the far right of a horizontal scroll bar or the bottom of a vertical scroll bar.


TScrollBar::SmallChange

TScrollBar	See also 	Example

Determines how much Position changes when the user clicks the arrow buttons on the scroll bar or presses the arrow keys on the keyboard.

__property Forms::TScrollBarInc SmallChange = {read=FSmallChange, write=FSmallChange, default=1};

Description

Set SmallChange to specify how much to change the value of Position when the user clicks on the arrow buttons. The Max and Min properties define the total range over which Position can vary.

For example, if Max is 100 and Min is 0, the scroll box can assume 100 positions. If the SmallChange property setting is 5 and the Position property is 0, the user can click the down or right arrow button 20 times before the thumb tab is moved all the way to the end of the scroll bar.

SmallChange should correspond to the portion of this range that the user sees as one line or one item, expressed in the logical units used by the Max, Min, and Position properties.


TScrollBar events

TScrollBar	Alphabetically	Legend

In TScrollBar

OnChange

OnScroll

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TScrollBar events

TScrollBar	By object	Legend

OnChange

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnScroll

OnStartDrag


TScrollBar::OnChange

TScrollBar	See also

Occurs immediately after the value of Position changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to control another object or group of objects using TScrollBar. Adjust the objects controlled by the scrollbar to reflect the new value of Position.

OnChange occurs whether the value of Position is changed by the user or programmatically. If the value of Position is changed by the user, OnChange occurs immediately after the OnScroll event.


TScrollBar::OnScroll

TScrollBar	See also 	Example

Occurs when the user scrolls the scroll bar with the mouse or keyboard.

__property TScrollEvent OnScroll = {read=FOnScroll, write=FOnScroll};

Description

Write an OnScroll to adjust the value of Position when the user scrolls the scroll bar. The ScrollPos parameter contains the new value that is about to be assigned to the Position property as a result of the scroll. Change ScrollPos to alter the result of the scroll.

The ScrollCode parameter indicates the type of user action that just scrolled the scrollbar. The ScrollCode parameter is one of these values:

Value	Meaning

scLineUp	User clicked the top or left scroll arrow or pressed the Up or Left arrow key.

scLineDown	User clicked the bottom or right scroll arrow or pressed the Down or Right arrow key.

scPageUp	User clicked the area to the left of the thumb tab or pressed the PgUp key.

scPageDown	User clicked the area to the right of the thumb tab or pressed the PgDn key.

scPosition	User positioned the thumb tab and released it.

scTrack	User is moving the thumb tab.

scTop	User moved the thumb tab to the top or far left on the scroll bar.

scBottom	User moved the thumb tab to the bottom or far right on the scroll bar.

scEndScroll	User finished moving the thumb tab on the scroll bar.


TScrollBar methods

TScrollBar	Alphabetically

In TScrollBar

~TScrollBar

SetParams

TScrollBar

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TScrollBar methods

TScrollBar	By object

~TScrollBar

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetParams

SetTextBuf

Show

TScrollBar

Update

UpdateControlState


TScrollBar::TScrollBar

TScrollBar	See also

Creates and initializes an instance of TScrollBar.

__fastcall virtual TScrollBar(Classes::TComponent* AOwner);

Description

Call TScrollBar to create an instance of TScrollBar at runtime. Scroll bars placed on a form at design time are created automatically. TScrollBar calls the parent object’s constructor method, then sets the initial values for the scroll bar as follows:

•	ControlStyle is set to [csFramed, csDoubleClicks]

•	Height is set to the system horizontal scrollbar height, and Width to 121.

•	Kind is set to sbHorizontal.

•	Position is set to 0, Min to 0, and Max to 100.

•	SmallChange and LargeChange are both set to 1.

•	TabStop is set to true.


TScrollBar::SetParams

TScrollBar	See also

Sets the Position, Max, and Min property values all at once.

void __fastcall SetParams(int APosition, int AMin, int AMax);

Description

Use the SetParams method to set the Position, Max, and Min property values all at once, preventing repaints that would occur if each property value were set separately.


TScrollBar::~TScrollBar

TScrollBar

~TScrollBar frees the memory associated with the TScrollBar object.

__fastcall virtual ~TScrollBar(void) { }

Description

Do not call ~TScrollBar directly. Instead, use the delete keyword on the object, which causes ~TScrollBar to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


 TScrollBox

Hierarchy	Properties	Methods	Events	See also

TScrollBox represents a scrolling area (a scroll box) in a window.

Unit

forms

Description

Use TScrollBox to create a scroll box in a window.

One use of a scroll box is to prevent areas of a window, such as a toolbar or status bar (TPanel components), from scrolling. To prevent a toolbar and status bar from scrolling, hide the window’s scroll bars, and then position a scroll box in the client area of the window between the toolbar and status bar. The scroll bars associated with the scroll box will appear to belong to the window, but will scroll only the area inside the scroll box.

Another use of scroll boxes is to create multiple scrolling areas (views) in a window. Views are common in commercial word-processor, spreadsheet, and project management applications.

A scroll box can contain objects, such as TButton and TCheckBox objects.


TScrollBox properties

TScrollBox	Alphabetically	Legend

In TScrollBox

BorderStyle

Derived from TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TScrollBox properties

TScrollBox	By object	Legend

Align

AutoScroll

BorderStyle

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

HorzScrollBar

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

VertScrollBar

Visible

Width

WindowProc


TScrollBox::BorderStyle

TScrollBox

Specifies whether the scroll box has a border.

__property TBorderStyle BorderStyle = {read=FBorderStyle, write=SetBorderStyle, default=1};

Description

Use BorderStyle to get or set whether the scroll box has a border. BorderStyle can be one of the following TBorderStyle values:

Value	Meaning

bsNone	No visible border

bsSingle	Single-line border


TScrollBox events

TScrollBox	Alphabetically	Legend

In TScrollBox

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp


TScrollBox events

TScrollBox	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnResize


TScrollBox::OnResize

TScrollBox

Occurs when the scroll box is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

Use OnResize to perform special processing when the scroll box is resized.


TScrollBox methods

TScrollBox	Alphabetically

In TScrollBox

~TScrollBox

TScrollBox

Derived from TScrollingWinControl

DisableAutoRange

EnableAutoRange

ScrollInView

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TScrollBox methods

TScrollBox	By object

~TScrollBox

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TScrollBox

Update

UpdateControlState


TScrollBox::TScrollBox

TScrollBox	See also

Creates and initializes a new TScrollBox object.

__fastcall virtual TScrollBox(Classes::TComponent* AOwner);

__fastcall TScrollBox(HWND ParentWindow) : Forms::TScrollingWinControl(ParentWindow) { }

Description

Use TScrollBox indirectly, using the new keyword, to create and initialize a new TScrollBox object at runtime.

Pass a single component as a parameter to provide the TScrollBox object with an owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the scroll box in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

AOwner is a TComponent object that encapsulates the parent object for the scroll box.

TScrollBox performs the following tasks:

•	Calls the TScrollingWinControl::TScrollBox method, passing it AOwner.

•	Sets the TScrollingWinControl::ControlStyle property to csAcceptsControls, csCaptureMouse, csClickEvents, csSetCaption, csDoubleClicks.

•	Sets the TScrollingWinControl::Width property to 185.

•	Sets the TScrollingWinControl::Height property to 41.

•	Sets the BorderStyle property to bsSingle.


TScrollBox::~TScrollBox

TScrollBox

Frees the memory associated with the TScrollBox object.

__fastcall virtual ~TScrollBox(void) { }

Description

Do not call ~TScrollBox directly. Instead, use the delete keyword on the object, which causes ~TScrollBox to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl


TScrollingWinControl

Hierarchy	Properties	Methods	See also

TScrollingWinControl is the base class for windowed controls that support scrolling.

Unit

forms

Description

Use TScrollingWinControl as a base class when defining a custom windowed control that supports scrolling.

Typically, a scrolling windowed control has horizontal and vertical scroll bars and scrolls a child control into view when the child control receives focus.

Examples of scrolling windowed controls include TForm and TScrollBox objects.


TScrollingWinControl properties

TScrollingWinControl	Alphabetically	Legend

In TScrollingWinControl

AutoScroll

HorzScrollBar

VertScrollBar

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TScrollingWinControl properties

TScrollingWinControl	By object	Legend

Align

AutoScroll

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

HorzScrollBar

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

VertScrollBar

Visible

Width

WindowProc


TScrollingWinControl::AutoScroll

TScrollingWinControl	See also

Indicates whether scroll bars appear automatically on the scrolling windowed control if it is not large enough to display all of its controls.

__property bool AutoScroll = {read=FAutoScroll, write=SetAutoScroll, default=1};

Description

If AutoScroll is true, the scroll bars appear automatically when necessary. For example, if the user resizes the scrolling windowed control so that some of its controls are partially obscured, scroll bars appear.

If AutoScroll is false, scroll bars don’t appear automatically. In this case, use the HorzScrollBar and VertScrollBar properties to make scroll bars appear.


TScrollingWinControl::HorzScrollBar

TScrollingWinControl	See also 	Example

Represents the horizontal scroll bar for the scrolling windowed control.

__property TControlScrollBar* HorzScrollBar = {read=FHorzScrollBar, write=SetHorzScrollBar};

Description

Use HorzScrollBar to hide, show, or manipulate the horizontal scroll bar for the scrolling windowed control.


TScrollingWinControl::VertScrollBar

TScrollingWinControl	See also

Represents the vertical scroll bar for the scrolling windowed control.

__property TControlScrollBar* VertScrollBar = {read=FVertScrollBar, write=SetVertScrollBar};

Description

Use VertScrollBar to hide, show, or manipulate the vertical scroll bar for the scrolling windowed control.


TScrollingWinControl methods

TScrollingWinControl	Alphabetically	Legend

In TScrollingWinControl

~TScrollingWinControl

AlignControls

AutoScrollInView

ChangeScale

CreateParams

CreateWnd

DisableAutoRange

EnableAutoRange

ScrollInView

TScrollingWinControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TScrollingWinControl methods

TScrollingWinControl	By object	Legend

~TScrollingWinControl

AlignControls

Assign

AutoScrollInView

BeginDrag

BringToFront

Broadcast

CanFocus

ChangeScale

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CreateParams

CreateWnd

DefaultHandler

DestroyComponents

Destroying

DisableAlign

DisableAutoRange

Dispatch

DragDrop

Dragging

EnableAlign

EnableAutoRange

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

ScrollInView

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TScrollingWinControl

Update

UpdateControlState


TScrollingWinControl::AlignControls

TScrollingWinControl	See also

Aligns the controls in the scrolling windowed control.

virtual void __fastcall AlignControls(Controls::TControl* AControl, Windows::TRect &ARect);

Description

Use AlignControls to align the controls in the scrolling windowed control  according to the values of their Align properties.

AControl is a TControl object specifying the control that takes precedence in alignment when other controls have the same Align value. AControl can be NULL.

ARect is a TRect object specifying the area in the scrolling windowed control that contains the controls to align. ARect is automatically set to the entire area of the scrolling windowed control.

If AutoScroll is true and the scrolling windowed control is not being resized,  the ranges of the scroll bars on the scrolling windowed control are automatically recalculated.

After recalculating the ranges of the scroll bars and setting the value of ARect, AlignControls calls TWinControl::AlignControls, passing the AControl and ARect objects.


TScrollingWinControl::AutoScrollInView

TScrollingWinControl	See also

Scrolls a control into the visible area of the scrolling windowed control.

void __fastcall AutoScrollInView(Controls::TControl* AControl);

Description

Use AutoScrollInView to scroll the control specified by the AControl parameter into the visible area of the scrolling windowed control.

Unlike ScrollInView, AutoScrollInView does not perform scrolling when the scrolling windowed control or the specified control are being loaded from a stream.

AutoScrollInView calls ScrollInView to perform any needed scrolling.


TScrollingWinControl::ChangeScale

TScrollingWinControl	See also

Resizes the scrolling windowed control by a specific ratio.

DYNAMIC void __fastcall ChangeScale(int M, int D);

Description

Use ChangeScale to resize the scrolling windowed control by a specific ratio.

M is the multiplier of the ratio; D is the divisor of the ratio. For example, to resize the scrolling windowed control to four-fifths of its current size, set M to four and D to five.

ChangeScale recalculates the ranges of the scroll bars on the scrolling windowed control according to the ratio, and then calls TControl::ChangeScale.


TScrollingWinControl::TScrollingWinControl

TScrollingWinControl	See also

Creates and initializes a new TScrollingWinControl object.

__fastcall virtual TScrollingWinControl(Classes::TComponent* AOwner);

__fastcall TScrollingWinControl(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not instantiate a TScrollingWinControl object. To add a lookup control to a form, create an instance of a TScrollingWinControl descendant using the new keyword.

In the first syntax, AOwner is a TComponent object that owns the scrolling windowed control. In the second syntax, ParentWindow is a non-VCL window that hosts the scrolling windowed control.

After calling the parent object’s constructor, TScrollingWinControl performs the following tasks:

•	Creates horizontal and vertical scroll bar objects and assigns them to HorzScrollBar and VertScrollBar respectively.

•	Sets AutoScroll to true.


TScrollingWinControl::TScrollingWinControl
TScrollingWinControl::CreateParams

TScrollingWinControl

Initializes the window creation parameters so that the entire window is not redrawn when the width or height of the client area changes.

virtual void __fastcall CreateParams(Controls::TCreateParams &Params);

Description

CreateParams calls the parent class's method and uses that Window class style, removing the CS_HREDRAW and CS_VREDRAW styles from it.

By removing these styles the form will only redraw the invalidated regions, not the entire window.


TScrollingWinControl::TScrollingWinControl
TScrollingWinControl::CreateWnd

TScrollingWinControl	See also

Creates a Windows control corresponding to the TScrollingWinControl object.

virtual void __fastcall CreateWnd(void);

Description

Use CreateWnd to create a Windows control corresponding to the ScrollingWinControl object.

CreateWnd initializes the scroll bars on the scrolling windowed control and then calls TWinControl::CreateWnd.


TScrollingWinControl::~TScrollingWinControl

TScrollingWinControl	See also

Removes the TScrollingWinControl object from memory.

__fastcall virtual ~TScrollingWinControl(void);

Description

Do not call ~TScrollingWinControl. Instead, call Free, which calls ~TScrollingWinControl if the TScrollingWinControl object is not NULL.

~TScrollingWinControl frees the HorzScrollBar and VertScrollBar properties and then calls TWinControl::~TScrollingWinControl.


TScrollingWinControl::DisableAutoRange

TScrollingWinControl	See also

Disables automatic scrolling.

void __fastcall DisableAutoRange(void);

Description

Use DisableAutoRange to temporarily disable scrolling when rearranging controls on a form.  Use the EnableAutoRange method to turn scrolling on again when finished rearranging the controls.


TScrollingWinControl::EnableAutoRange

TScrollingWinControl	See also

Enables automatic scrolling.

void __fastcall EnableAutoRange(void);

Description

Use EnableAutoRange to reenable scrolling after turning it off. This method can be used  with the DisableAutoRange method to turn scrolling on and off.


TScrollingWinControl::ScrollInView

TScrollingWinControl	See also

Scrolls a control into the visible area of the scrolling windowed control.

void __fastcall ScrollInView(Controls::TControl* AControl);

Description

Use ScrollInView to ensure that a specified control is in the visible area of the scrolling windowed control. AControl specifies the TControl object to scroll into view.

Note:	If the ComponentState property for AControl or the scrolling windowed control might be csLoading, use AutoScrollInView instead.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TSessionList

Hierarchy	Properties	Methods	See also

TSessionList provides management of Borland Database Engine (BDE) sessions within a database application.

Unit

dbtables

Description

Use TSessionList to manage session components in applications that provide multiple sessions. C++Builder automatically creates a globally accessible default session list component named Sessions for all database applications. In a multi-session application there can be more than one active session, but only one session can be current at a time. TSessionList enables an application to switch current sessions.

Note:	Applications should not instantiate additional session list components.


TSessionList properties

TSessionList	Alphabetically	Legend

In TSessionList

Count

CurrentSession

List

Sessions


TSessionList properties

TSessionList	By object	Legend

Count

CurrentSession

List

Sessions


TSessionList::Count

TSessionList	See also 	Example

Indicates the number of available sessions for the application.

__property int Count = {read=GetCount, nodefault};

Description

Read Count to determine the current number of available sessions. Count is typically used to iterate through the list of available sessions to perform some universal action on all sessions. Used with the Sessions property, which enables an application to access a session by index number, Count specifies the maximum number of index entries for Sessions (Count - 1).


TSessionList::CurrentSession

TSessionList	See also

Returns a pointer to the current session component

__property TSession* CurrentSession = {read=GetCurrentSession, write=SetCurrentSession};

Description

Use CurrentSession to determine or specify which session in a database application is the current session. By default the current session is a pointer to the default session component, Session, that is created automatically by C++Builder for all database applications. Setting CurrentSession makes the specified session component the current one. While any number of sessions may be active, only one session can be current at a time.


TSessionList::List

TSessionList	See also

Returns a specified session component.

__property TSession* List[System::AnsiString SessionName] = {read=GetSessionByName};

Description

Use List to return a pointer to a specific session component managed by the session list. List does not change which session is current. SessionName specifies the session component to return, and must match the SessionName property of an existing session component. If no such session exists, List raises an EDatabaseError exception with a message specifying the invalid session name.

Note:	To prevent raising an exception, call the FindSession method instead of using the List property.


TSessionList::Sessions

TSessionList	See also 	Example

Lists all active session components in the session list.

__property TSession* Sessions[int Index] = {read=GetSession};

Description

Use Sessions to access available session components. Index specifies the session to access. Index must be in the range of zero to the current value of the Count property minus one, or an EListError exception is raised describing the out of bounds condition.

For example, an application might iterate through all available sessions in the list to perform a global action on them.


TSessionList methods

TSessionList	Alphabetically

In TSessionList

~TSessionList

FindSession

GetSessionNames

OpenSession

TSessionList

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TSessionList methods

TSessionList	By object

~TSessionList

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

FindSession

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetSessionNames

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

OpenSession

SafeCallException

TSessionList


TSessionList::TSessionList

TSessionList	See also

Creates an instance of a TSessionList component.

__fastcall TSessionList(void);

Description

Do not create instances of TSessionList. A default session list component, Sessions, is automatically created for all database applications. Secondary session lists are not necessary.

TSessionList calls its parent object’s constructor, creates an empty list object to keep track of session components, and both creates and initializes a critical section for opening databases.


TSessionList::~TSessionList

TSessionList	See also

Destroys the instance of a session list component.

__fastcall virtual ~TSessionList(void);

Description

Do not call ~TSessionList. C++Builder automatically handles the destruction of the default session list component, Sessions, when an application closes.

~TSessionList closes all session components, deletes the BDE critical section, and calls its parent object’s destructor.


TSessionList::FindSession

TSessionList	See also

Searches the list of sessions for a specified session.

TSession* __fastcall FindSession(const System::AnsiString SessionName);

Description

Call FindSession to determine whether or not a specified session exists. SessionName specifies the session to search for.

FindSession compares the SessionName parameter to the SessionName property for each session component in the session list. If a match is found, FindSession returns a pointer to the session component. If an application passes an empty string in SessionName, FindSession returns the default session, Session. If a match is not found, FindSession returns NULL.


TSessionList::GetSessionNames

TSessionList	See also 	Example

Populates a string list with the names of all available sessions.

void __fastcall GetSessionNames(Classes::TStrings* List);

Description

Call GetSessionNames to retrieve a list of all available sessions. List is a string list object, created and maintained by the application, into which to store session names. Names returned by GetSessionNames correspond to the SessionName properties of all available sessions.


TSessionList::OpenSession

TSessionList	See also

Makes an existing session active, or creates a new session component and makes it active.

TSession* __fastcall OpenSession(const System::AnsiString SessionName);

Description

Call OpenSession to make an existing session active, or to create a new session and make it active. SessionName specifies the name of the session to open.

OpenSession calls FindSession to see if the session specified in the SessionName parameter already exists. If it finds a match, it starts that session if necessary, and makes the session active. If OpenSession does not find an existing session, it creates a new session using the name specified in the SessionName parameter, starts the session, and makes it active.

In either case, OpenSession returns the session object.


Accessibility

Read-only


Hierarchy

TObject


 TSession

Hierarchy	Properties	Methods	Events	See also

TSession provides global management of a group of database connections within an application.

Unit

dbtables

Description

Use TSession to manage a group of database connections within an application. There are three uses for TSession: standard, multiple net files for Paradox, and multi-threaded database applications.

C++Builder automatically creates a globally accessible default TSession component named Session for all database applications. The default session component handles standard database connections. An application can control the default session by accessing its properties, events, and methods at runtime.

Database applications that must simultaneously access Paradox tables located in different network locations can establish multiple sessions, one for each network location.

Finally, database applications that must establish multiple, concurrent connections to the same database, such as performing two queries against the same data at once, are multi-threaded applications. Multi-threaded applications must create and maintain one additional session component for each simultaneous connection to a single database server.

Note:	Applications that maintain multiple sessions can manage them through the TSessionList component. A default session list component, called Sessions—note the plural which distinguishes it from the default session component, Session—is automatically created for all database applications.


TSession properties

TSession	Alphabetically	Legend

In TSession

Active

AutoSessionName

ConfigMode

DatabaseCount

Databases

Handle

KeepConnections

Locale

NetFileDir

PrivateDir

SessionName

SQLHourGlass

TraceFlags

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TSession properties

TSession	By object	Legend

AutoSessionName

ConfigMode

DatabaseCount

Databases

Handle

KeepConnections

Locale

NetFileDir

PrivateDir

SessionName

SQLHourGlass

TraceFlags

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject

Active


TSession::Active

TSession	See also

Specifies whether or not a session is active.

__property bool Active = {read=GetActive, write=SetActive, default=0};

Description

Examine Active at runtime for the default session, Session, to determine if it is active or not. Active is false by default, meaning there are no open database connections or datasets associated with the session. If Active is true, the session is active even if there are currently no active database connections.

Set the Active property at design time or runtime for additional session components in a database application. Setting Active to true starts the session and makes it the current session. Setting Active to true triggers an OnStartup event handler for the session and initializes the NetFileDir, PrivateDir, and ConfigMode properties.

Setting Active to false (the default), closes any open datasets, and disconnects from attached database servers.

Note:	An application can close the default session by setting Active to false, but this is not recommended.


TSession::AutoSessionName

TSession	See also

Indicates whether or not a unique session name is automatically generated for a session.

__property bool AutoSessionName = {read=FAutoSessionName, write=SetAutoSessionName, default=0};

Description

Set AutoSessionName to control whether or not a unique session name is automatically generated. AutoSessionName is intended to guarantee developers of multi-threaded applications that sessions spawned for each thread are unique at runtime.

When AutoSessionName is false (the default), the application must set the SessionName property for a session component. When AutoSessionName is true, TSession assigns the SessionName property automatically and replicates the session name across the SessionName properties of all dataset components in the data module or form where the session component appears. This allows applications to use sessions in data modules that are replicated over multiple threads. TSession constructs a session name by taking the current value of the Name property and appending an underscore (_) followed by a numeric value. For example, if Name is CustomerSession, then the AutoSessionName might be CustomerSession_2.

Note:	The following restrictions apply to AutoSessionName:

•	You cannot set AutoSessionName for a session in a data module or form that contains more than one session component.

•	You cannot add a session component to a data module or form that already contains a session component with AutoSessionName set to true.

•	You cannot directly set the SessionName property of a session when AutoSessionName is true.


TSession::ConfigMode

TSession	See also 	Example

Specifies how the Borland Database Engine (BDE) should handle aliases for the session.

__property TConfigMode ConfigMode = {read=GetConfigMode, write=SetConfigMode, nodefault};

Description

Set ConfigMode to specify how the BDE should handle aliases created using the AddAlias or AddStandardAlias methods within the context of a session. ConfigMode also determines which BDE aliases are reported to a session when an application calls the GetAliasNames method.

The default setting for ConfigMode is cmAll, which is a constant that includes all possible set items defined in TConfigModes. The following table summarizes the possible BDE configuration modes that can be set for aliases:

Mode	Meaning

cfmVirtual	All aliases in the BDE configuration file, the BDE persistent store, and aliases local to the session are available to the session.

cfmPersistent	Only aliases in the BDE configuration file, or that are added to the persistent store are available to the session.

cfmSession	Only aliases created within this session are available to the session.

The main purpose of ConfigMode is to enable an application to specify and restrict aliases at the session level.

Note:	Aliases created within a session are not automatically saved to the BDE configuration file. To save an alias to the configuration file, call the SaveConfigFile method.


TSession::DatabaseCount

TSession	See also 	Example

Indicates the number of active database components currently associated with the session.

__property int DatabaseCount = {read=GetDatabaseCount, nodefault};

Description

Examine DatabaseCount to determine the number of active database components associated with a session. As database connections are opened or closed during a session’s life-span, this number can change. If DatabaseCount is zero, there are currently no active database components for the session.

DatabaseCount is typically used with the Databases property to iterate through the current set of active databases in a session.


TSession::Databases

TSession	See also 	Example

Provides an indexed array of all active database component names for a session.

__property TDatabase* Databases[int Index] = {read=GetDatabase};

Description

Use Databases to access active database components associated with a session. An active database is one that is currently connected to a database server.

Databases is typically used with the DatabaseCount property to iterate through the current set of active databases in a session.


TSession::Handle

TSession	See also

Specifies the Borland Database Engine (BDE) handle for the session.

__property Bde::hDBISes Handle = {read=GetHandle};

Description

Use Handle only to bypass TSession methods and write directly to the BDE API. Many BDE function calls require a handle parameter. Handle is assigned an initial value when a session is activated.

Note:	Do not use this property unless an application requires BDE functionality not available through standard C++Builder components.


TSession::KeepConnections

TSession	See also

Specifies whether or not a temporary database component created in the context of a session maintains a database server connection even if there are no active datasets associated with the database component.

__property bool KeepConnections = {read=FKeepConnections, write=FKeepConnections, default=1};

Description

Use KeepConnections to specify whether or not temporary database components created at runtime maintain server connections even when they have no active datasets. If KeepConnections is true (the default), the application maintains database connections until the application exits or calls the DropConnections method. For connections to remote database servers, or for applications that frequently open and close datasets, KeepConnections should remain true to reduce network traffic and speed up processing.

When KeepConnections is false, an application disconnects from a database when all datasets associated with a database component are closed. Dropping a connection releases system resources allocated to the connection, but if a dataset is later reopened that uses the same database, the connection must be reestablished and initialized.

Note:	Duration of server connection for a persistent database component is determined by the database component’s KeepConnection property instead of the session’s KeepConnections property.


TSession::Locale

TSession	See also

Identifies the Borland Database Engine (BDE) language driver for the session component.

__property void * Locale = {read=FLocale};

Description

Examine Locale to determine the BDE language driver used by the session component. Applications that make direct calls to the BDE may need to pass Locale information as an API function parameter.

Note:	Do not use this property unless an application requires BDE functionality not available through standard data access components.


TSession::NetFileDir

TSession	See also

Specifies the directory that contains the Borland Database Engine (BDE) network control file, PDOXUSRS.NET.

__property System::AnsiString NetFileDir = {read=GetNetFileDir, write=SetNetFileDir};

Description

Use NetFileDir to specify the directory that contains the BDE network control file, PDOXUSER.NET. This file governs the sharing of Paradox tables on network drives. All applications that share Paradox tables on a network directory must specify the same value for this property, and must have read, write, and create rights for the directory.

C++Builder derives an initial value for NetFileDir from the BDE configuration file for the Paradox driver. Any value assigned to NetFileDir at design time or runtime overrides the BDE configuration setting.


TSession::PrivateDir

TSession	See also

Specifies the directory in which to store temporary table processing files generated by the Borland Database Engine (BDE) for database components associated with a session.

__property System::AnsiString PrivateDir = {read=GetPrivateDir, write=SetPrivateDir};

Description

Use PrivateDir to set the directory in which to store temporary table processing files for all database connections, such as those generated by the BDE to handle local SQL statements. Ordinarily this value is only set at runtime, so that a user’s local hard disk is used to store temporary files. Local storage of these files improves performance. If no value is specified for PrivateDir, the BDE automatically stores temporary files in the directory current at the time the BDE was initialized.

Note:	For applications that run directly from a networked file server, the application should set PrivateDir to a user’s local drive to improve performance and to prevent temporary files from being created on the server where they might conflict with temporary files created by other instances of the application.


TSession::SessionName

TSession	See also

Specifies a unique session name that can be used by database and dataset components to link to this session.

__property System::AnsiString SessionName = {read=FSessionName, write=SetSessionName, stored=SessionNameStored};

Description

Set SessionName to a unique and meaningful name that can be used to link database and dataset components to the session. Database and dataset components each have corresponding SessionName properties that must either match the SessionName property of an active session or that be blank, indicating that they should be associated with the default session, Session.

Note:	If the AutoSessionName property is true, an application cannot set SessionName directly.


TSession::SQLHourGlass

TSession

Indicates whether or not the mouse cursor changes to an hourglass during BDE operations.

__property bool SQLHourGlass = {read=FSQLHourGlass, write=FSQLHourGlass, default=1};

Description

Set SQLHourGlass to false if you do not want the mouse cursor to change to an hourglass while the BDE is waiting for an SQL server to perform an operation. This property must be set before the session is opened.


TSession::TraceFlags

TSession	See also

Specifies the database operations to track with the SQL Monitor at runtime.

enum TTraceFlag { tfQPrepare, tfQExecute, tfError, tfStmt, tfConnect, tfTransact, tfBlob, tfMisc, tfVendor, tfDataIn, tfDataOut };

typedef Set<TTraceFlag, tfQPrepare, tfDataOut> TTraceFlags;

__property TTraceFlags TraceFlags = {read=FTraceFlags, write=SetTraceFlags, nodefault};

Description

Use TraceFlags to specify which database operations the SQL Monitor should track in an application at runtime. TraceFlags is only meaningful for the SQL Monitor, which is provided to enable performance tuning and SQL debugging when working with remote SQL database servers.

Note:	Normally trace options are set from the SQL Monitor rather than setting TraceFlags in application code.

The value of a session component’s TraceFlags property determines the initial settings of the TraceFlags property for database components associated with the session.

The TTraceFlags type defines the individual values that can be included in the TraceFlags property. The following table summarizes those values:

Values	Meaning

tfQPrepare	Monitor Prepare statements.

tfQExecute	Monitor ExecSQL statements.

tfError	Monitor server error messages. Such messages may include an error code.

tfStmt	Monitor all SQL statements.

tfConnect	Monitor database connect and disconnect operations, including allocation of connection handles, and freeing connection handles.

tfTransact	Monitor transaction statements, such as StartTransaction, Commit, and Rollback.

tfBlob	Monitor operations on blob data types.

tfMisc	Monitor any statements not covered by other flag options.

tfVendor	Monitor direct API function calls to the database server.

tfDataIn	Monitor data received from a server.

tfDataOut	Monitor data sent to a server.

Because TraceFlags is a set property, an application can specify different combinations of flags to monitor different combinations of statements. For example, the following statement limits monitoring to database connections and SQL statement preparation:

TraceFlags << tfConnect << tfQPrepare;


TSession events

TSession	Alphabetically	Legend

In TSession

OnPassword

OnStartup


TSession events

TSession	By object	Legend

OnStartup

OnPassword


TSession::OnPassword

TSession	See also

Occurs when an application attempts to open a Paradox table for the first time and the Borland Database Engine (BDE) reports insufficient access rights.

__property TPasswordEvent OnPassword = {read=FOnPassword, write=FOnPassword};

Description

Write an OnPassword event handler to take specific action when an application attempts to open a password-protected Paradox table for the first time. To gain access to the Paradox table, the event handler must pass a valid password to the BDE. The event handler should call the AddPassword method to make the password available to the session.

Note:	If an OnPassword event does not exist, but the BDE reports insufficient access rights, C++Builder displays a default dialog box that prompts for a password.


TSession::OnStartup

TSession	See also

Occurs when an application activates a session.

__property Classes::TNotifyEvent OnStartup = {read=FOnStartup, write=FOnStartup};

Description

Write an OnStartup event handler to take specific actions when an application activates a session. A session is activated by setting its Active property to true, or by opening a database or dataset associated with the session (both of which set Active to true).


TSession methods

TSession	Alphabetically

In TSession

~TSession

AddAlias

AddDriver

AddPassword

AddStandardAlias

Close

CloseDatabase

DeleteAlias

DeleteDriver

DropConnections

FindDatabase

GetAliasDriverName

GetAliasNames

GetAliasParams

GetConfigParams

GetDatabaseNames

GetDriverNames

GetDriverParams

GetPassword

GetStoredProcNames

GetTableNames

IsAlias

ModifyAlias

ModifyDriver

Open

OpenDatabase

RemoveAllPasswords

RemovePassword

SaveConfigFile

TSession

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSession methods

TSession	By object

~TSession

AddAlias

AddDriver

AddPassword

AddStandardAlias

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

CloseDatabase

DefaultHandler

DeleteAlias

DeleteDriver

DestroyComponents

Destroying

Dispatch

DropConnections

FieldAddress

FindComponent

FindDatabase

Free

FreeInstance

FreeNotification

FreeOnRelease

GetAliasDriverName

GetAliasNames

GetAliasParams

GetConfigParams

GetDatabaseNames

GetDriverNames

GetDriverParams

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetPassword

GetStoredProcNames

GetTableNames

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsAlias

MethodAddress

MethodName

ModifyAlias

ModifyDriver

NewInstance

Open

OpenDatabase

RemoveAllPasswords

RemoveComponent

RemovePassword

SafeCallException

SaveConfigFile

TSession


TSession::AddAlias

TSession	See also 	Example

Adds a specified Borland Database Engine (BDE) alias to the session for an SQL database server.

void __fastcall AddAlias(const System::AnsiString Name, const System::AnsiString Driver, Classes::TStrings* List);

Description

Call AddAlias at runtime to create a session-specific BDE alias for an SQL database server. Name is the unique name to assign to the alias. Driver is the name of the SQL Links database driver to use for the alias. List is a string list containing parameters for the alias.

A session’s ConfigMode property determines whether an alias is local to the session, or is available to all applications in the BDE persistent store as long as any BDE clients are active. To save an alias permanently, call the SaveConfigFile method before ending the session.

Note:	Although AddAlias can be used to create a Paradox or dBASE alias, AddStandardAlias provides a simpler method for Paradox and dBASE alias creation.


TSession::AddDriver

TSession	See also

Adds a specified Borland Database Engine (BDE) driver to the session for an SQL database server.

void __fastcall AddDriver(const System::AnsiString Name, Classes::TStrings* List);

Description

Call AddDriver at runtime to create a BDE driver for an SQL database server. AddDriver can also be used to create ODBC driver entries. Name is the unique name to assign to the driver. List is a string list containing parameters for the alias.

A session’s ConfigMode property determines whether a driver is local to the session, or is available to all applications in the BDE persistent store as long as any BDE clients are active. To save a driver permanently, call the SaveConfigFile method before ending the session.


TSession::AddPassword

TSession	See also

Adds a password to the current session for accessing encrypted Paradox tables.

void __fastcall AddPassword(const System::AnsiString Password);

Description

Call AddPassword to provide a password for a session prior to opening an encrypted Paradox table that requires a password. If an application opens a Paradox table that requires a password for access, the session does not have a password assigned to it, and the application does not provide its own OnPassword event handler, C++Builder displays a dialog box prompting the user for a valid password before allowing table access.

Note:	If an application defines its own OnPassword event handler, the handler should call this method to add passwords for the session. All passwords assigned by AddPassword should be deleted with RemoveAllPasswords or RemovePassword before an application closes.


TSession::AddStandardAlias

TSession	See also 	Example

Adds a standard Borland Database Engine (BDE) alias to the session for Paradox, dBASE, or ASCII tables.

void __fastcall AddStandardAlias(const System::AnsiString Name, const System::AnsiString Path, const System::AnsiString DefaultDriver);

Description

Call AddStandardAlias at runtime to create a session-specific BDE alias for Paradox, dBASE or ASCII tables. Name is the unique name to assign to the alias. Path specifies the directory where the database is located. DefaultDriver is the name of the standard BDE driver to use for the alias. If set, DefaultDriver must be one of “Paradox,” “DBASE,” or “ASCIIDRV”. If left blank DefaultDriver defaults to “Paradox”. DefaultDriver is used when attempting to open a table that both does not have an extension and is defined as a table of type ttDefault.

A session’s ConfigMode property determines whether an alias is local to the session, or is available to all applications in the BDE persistent store as long as any BDE clients are active. the lifetime of the session. To save an alias permanently, call the SaveConfigFile method before ending the session.

Note:	To create an alias for an SQL database, call AddAlias instead of AddStandardAlias.


TSession::Close

TSession	See also

Disconnects from all databases, and closes the session.

void __fastcall Close(void);

Description

Call Close to end a session. Close disconnects from all active databases by freeing temporary database components, and calling the Close methods persistent database components, and then sets its own session handle to NULL.

Note:	Setting the Active property to false also closes a session.


TSession::CloseDatabase

TSession	See also

Closes a database connection associated with the current session.

void __fastcall CloseDatabase(TDatabase* Database);

Description

Call CloseDatabase to close a persistent database connection, or to close and free a temporary database connection. Database specifies the name of the database component for which to close the connection.

CloseDatabase decrements the specified database component’s reference count, and then, if the reference count is zero and the database component’s KeepConnection property is false, CloseDatabase either frees a temporary database component or closes the connection for a persistent database component.

Note:	Calling CloseDatabase for a persistent database component does not close the connection. To close a connection for a persistent database component, call the database component’s Close method directly.

Temporary database components are closed automatically when the last dataset associated with the database component is closed, but an application can call CloseDatabase prior to that time to force closure. Closing a connection established by a temporary database component does not free the component if the session’s KeepConnections property is true (the default). To free temporary database components after closing their connections call DropConnections.


TSession::TSession

TSession	See also

Creates an instance of a TSession component.

__fastcall virtual TSession(Classes::TComponent* AOwner);

Description

Do not call TSession directly. The default session component, Session, is created automatically for all database applications. To create additional sessions for a multi-threaded database application at runtime call Sessions::OpenSession instead of TSession. OpenSession calls TSession only if the session does not already exist. (At design time, create additional sessions by dropping them on a data module::)

TSession calls its parent object’s constructor and ensures that the session component cannot be inherited should the data module or form on which it is placed be stored in the Object Repository. TSession also:

•	Creates an empty list of database components for the session.

•	Sets the KeepConnections property to true.

•	Adds the session to the session list.

•	Sets the Handle property to NULL.


TSession::DeleteAlias

TSession	See also

Removes a specified Borland Database Engine (BDE) alias from the session.

void __fastcall DeleteAlias(const System::AnsiString Name);

Description

Call DeleteAlias to remove a BDE alias from a session. Removing an alias makes the alias unavailable to the session, but does not remove it from the BDE configuration file if the alias was stored there when it was created. To remove an alias from the BDE configuration file follow the call to DeleteAlias with a call to SaveConfigFile.


TSession::DeleteDriver

TSession	See also

Removes a specified Borland Database Engine (BDE) driver from the session.

void __fastcall DeleteDriver(const System::AnsiString Name);

Description

Call DeleteDriver to remove a BDE driver from a session. Removing a driver makes the driver unavailable to the session, but does not remove it from the BDE configuration file if the driver was stored there when it was created. To remove a driver from the BDE configuration file follow the call to DeleteDriver with a call to SaveConfigFile.


TSession::~TSession

TSession	See also

Destroys the instance of a session component.

__fastcall virtual ~TSession(void);

Description

Do not call ~TSession directly. For session components other than the default session, an application should call Free, which verifies that the session component is not already freed before calling ~TSession.

Warning: Never call Free or ~TSession for the default session. Freeing of the default session is handled automatically when an application terminates.

~TSession performs the following actions before calling its parent object’s destructor:

•	Makes the session inactive, which closes all database connections.

•	Removes the session from the session list.

•	Resets database session references, if necessary.

•	Frees the list of database components associated with the session.


TSession::DropConnections

TSession	See also

Frees all temporary database components associated with a session if they are inactive.

void __fastcall DropConnections(void);

Description

Use DropConnections to free all temporary database components that are currently inactive. If the KeepConnections property of the session is true (the default), then temporary database components created as needed for the session by C++Builder at runtime are not automatically freed when their database connections are closed. DropConnections enables an application to free these components when they are no longer needed.


TSession::FindDatabase

TSession	See also

Searches a session’s list of database components for a specified database.

TDatabase* __fastcall FindDatabase(const System::AnsiString DatabaseName);

Description

Call FindDatabase to determine whether or not a specified database is associated with a session. DatabaseName specifies the name of the database component for which to search.

FindDatabase compares DatabaseName to the DatabaseName property for each database component in a session’s list. If a match is found, FindDatabase returns a pointer to the database component. Otherwise FindDatabase returns NULL.

An application can call FindDatabase to see if a database component already exists before creating a new database component for a session.


TSession::GetAliasDriverName

TSession	See also

Provides the name of the database driver used by a specified Borland Database Engine (BDE) alias associated with the session.

System::AnsiString __fastcall GetAliasDriverName(const System::AnsiString AliasName);

Description

Call GetAliasDriverName to determine the BDE database driver used by a specific alias. AliasName is the name of the alias for which to return driver information.

For aliases corresponding to Paradox and dBASE tables, GetAliasDriverName returns “STANDARD”. For ASCII tables the return value is “ASCIIDRV”. For SQL databases, the driver name depends on the database server.


TSession::GetAliasNames

TSession	See also 	Example

Populates a string list with the names of persistent Borland Database Engine (BDE) aliases.

void __fastcall GetAliasNames(Classes::TStrings* List);

Description

Call GetAliasNames to retrieve a list of persistent BDE aliases—those aliases that exist in persistent storage or in the BDE configuration file. List is a string list object, created and maintained by the application, into which to store the alias names.

A session’s ConfigMode property determines whether an alias created in the context of this session is reported by GetAliasNames. If ConfigMode is cmAll, aliases created within the session are reported.


TSession::GetAliasParams

TSession	See also 	Example

Retrieves the parameters associated with a specified Borland Database Engine (BDE) alias.

void __fastcall GetAliasParams(const System::AnsiString AliasName, Classes::TStrings* List);

Description

Call GetAliasParams to retrieve the BDE configuration parameters for a specified alias. AliasName is the name of the alias for which to retrieve parameters. List is a string list object, created and maintained by the application, into which to store the parameters.


TSession::GetConfigParams

TSession	See also

Retrieves Borland Database Engine (BDE) configuration information.

void __fastcall GetConfigParams(const System::AnsiString Path, const System::AnsiString Section, Classes::TStrings* List);

Description

Call GetConfigParams to retrieve specific types of configuration information from the BDE configuration file used to initialize the application.

Path represents the internal node structure of the BDE configuration file, and must always start at the root, denoted by a backslash. Each node must be separated from others by a backslash, and no node may be empty. For example, a Path of \SYSTEM\FORMATS\TIME, returns the time format used by the BDE configuration file.

Path can contain a replaceable string formatting symbol (%s) in one of its node designations. If it does, Section must contain the missing node information. In this case, GetConfigParams inserts the contents of Section into Path before calling the BDE for the requested information.

List is a string list object, created and maintained by the application, into which to store the configuration information. For example, if Path is \DATABASES\%s\DB INFO, and Section is an alias name, then GetConfigParams returns the parameters for the alias in List.

For more information about the BDE Configuration File, see the on-line BDE help.


TSession::GetDatabaseNames

TSession	See also 	Example

Populates a string list with the names of persistent Borland Database Engine (BDE) aliases and the names of all databases components known to the session.

void __fastcall GetDatabaseNames(Classes::TStrings* List);

Description

Call GetDatabaseNames to retrieve a sorted, combined list of persistent BDE aliases—those aliases that exist in persistent storage or in the BDE configuration file—and the names of all database components known to the session. List is a string list object, created and maintained by the application, into which to store the database and alias names.


TSession::GetDriverNames

TSession	See also 	Example

Populates a string list with the names of all Borland Database Engine (BDE) drivers available to the session.

void __fastcall GetDriverNames(Classes::TStrings* List);

Description

Call GetDriverNames to retrieve the names of all BDE drivers that can be used by a session. List is a string list object, created and maintained by the application, into which to store the driver names.


TSession::GetDriverParams

TSession	See also 	Example

Populates a string list with the parameters for a specified Borland Database Engine (BDE) driver.

void __fastcall GetDriverParams(const System::AnsiString DriverName, Classes::TStrings* List);

Description

Call GetDriverParams to retrieve a list of parameters associated with a specified BDE driver. DriverName is the BDE driver for which to return a parameter list. List is a string list object, created and maintained by the application, into which to store the driver parameters.

The actual number of parameters returned by GetDriverParams depends on the specified driver. For example, for the STANDARD driver used by Paradox and dBASE, returns only a few parameters. For SQL Links drivers multiple parameters are returned.


TSession::GetPassword

TSession	See also

Invokes the OnPassword event handler for the session or displays the default password dialog box.

bool __fastcall GetPassword(void);

Description

Call GetPassword to invoke the OnPassword event handler for the session and handle response logic when an application is working with password-protected Paradox files. If an OnPassword event handler is not defined, GetPassword displays the default password dialog box.

An application can use the return value of GetPassword to control program logic. GetPassword returns true if a user chooses OK, or false if the user chooses Cancel.


TSession::GetStoredProcNames

TSession	See also 	Example

Populates a string list with the names of all stored procedures associated with a specified database component that is connected to an SQL database server.

void __fastcall GetStoredProcNames(const System::AnsiString DatabaseName, Classes::TStrings* List);

Description

Call GetStoredProcNames to retrieve a list of all stored procedures for a database component that is attached to an SQL database server. DatabaseName specifies the name of the database for which to retrieve stored procedure names. List is a string list object, created and maintained by the application, into which to return the stored procedure names.

Note:	GetStoredProcNames raises an exception if called on Paradox or dBASE databases.


TSession::GetTableNames

TSession	See also 	Example

Populates a string list with the names of tables associated with a specified database component.

void __fastcall GetTableNames(const System::AnsiString DatabaseName, const System::AnsiString Pattern, bool Extensions, bool SystemTables, Classes::TStrings* List);

Description

Call GetTableNames to retrieve a list of the tables associated with a given database. DatabaseName specifies the name of the database from which to retrieve table names.

Pattern specifies a delimiter string that restricts the tables returned to those that match the string. Pattern can include wildcard symbols. Pass an empty Pattern string to match all files not restricted by other criteria.

For searches on Paradox and dBASE, set Extensions to true to include filename extensions as part of the table name. For SQL-based databases, set Extension to false.

Set SystemTables to true for SQL-based databases to return both data tables and the system tables that define the database structure. Set SystemTables to false for Paradox and dBASE tables.

List is a string list object, created and maintained by the application, into which to return the table names.


TSession::IsAlias

TSession	See also

Determines whether or not a string value corresponds to an existing Borland Database Engine (BDE) database alias known to the session.

bool __fastcall IsAlias(const System::AnsiString Name);

Description

Call IsAlias to determine if a string corresponds to the name of an existing BDE alias that can be used by the session. Name is the string to test.

If IsAlias returns true, Name is a valid alias.

Note:	The aliases known to IsAlias depend on the session’s ConfigMode property. If ConfigMode is cmAll, then all aliases are available to the session.


TSession::ModifyAlias

TSession	See also

Adds or changes parameters for a Borland Database Engine (BDE) alias.

void __fastcall ModifyAlias(System::AnsiString Name, Classes::TStrings* List);

Description

Call ModifyAlias to change the parameters for a specified BDE alias. Name is the name of the alias to modify. List is a string list object previously populated with parameter values to add or change. An application must create and maintain List.

Populate List with parameter strings before calling ModifyAlias. List need only contain the parameters to change. If ModifyAlias passes a parameter for which a value already exists, the new parameter replaces the existing one. New parameters that are not yet defined for the alias are added to the existing parameters. If List is empty, ModifyAlias does not change any existing parameters.


TSession::ModifyDriver

TSession	See also

Adds or changes parameters for a Borland Database Engine (BDE) driver.

void __fastcall ModifyDriver(System::AnsiString Name, Classes::TStrings* List);

Description

Call ModifyDriver to change the parameters for a specified BDE database driver. Name is the name of the driver to modify. List is a string list object previously populated with parameter values to add or change. An application must create and maintain List.

Populate List with parameter strings before calling ModifyDriver. List need only contain the parameters to change. If ModifyDriver passes a parameter for which a value already exists, the new parameter replaces the existing one. New parameters that are not yet defined for the driver are added to the existing parameters. If List is empty, ModifyDriver does not change any existing parameters.

A session’s ConfigMode property determines whether a driver is local to the session, or is available to all applications in the BDE persistent store as long as any BDE clients are active. To save a driver permanently, call the SaveConfigFile method before ending the session.


TSession::Open

TSession	See also

Starts a session and makes it the current session.

void __fastcall Open(void);

Description

Call Open to start a session other than the default session in a database application. Open sets Active to true, triggers an OnStartup event handler for the session and initializes the NetFileDir, PrivateDir, and ConfigMode properties.


TSession::OpenDatabase

TSession	See also

Opens an existing database, or creates a temporary database component and opens it.

TDatabase* __fastcall OpenDatabase(const System::AnsiString DatabaseName);

Description

Call OpenDatabase to connect to a database for which a persistent database component already exists, or to create a temporary database component and connect to a database. DatabaseName specifies the database to open.

OpenDatabase makes the current session active, then calls FindDatabase to determine if the DatabaseName parameter corresponds to the DatabaseName property of an existing database component. If it does not, OpenDatabase creates a temporary database component, assigning the DatabaseName parameter to the DatabaseName property. Finally, OpenDatabase calls the Open method of the database to connect to a database server, then increments the session’s database reference count by one.


TSession::RemoveAllPasswords

TSession	See also

Deletes all passwords previously added to the current session for accessing encrypted Paradox tables.

void __fastcall RemoveAllPasswords(void);

Description

Call RemoveAllPasswords to delete all current Paradox table passwords associated with the current session. Subsequent attempts to access encrypted Paradox tables fail unless an application first calls AddPassword to reestablish a password.

Note:	Ordinarily an application should call RemoveAllPasswords to remove all session-specific passwords it creates from the Borland Database Engine (BDE) persistent store before terminating.


TSession::RemovePassword

TSession	See also

Deletes a single password previously added to the current session for accessing an encrypted Paradox table.

void __fastcall RemovePassword(const System::AnsiString Password);

Description

Call RemovePassword to delete a single Paradox table password associated with the current session from the Borland Database Engine (BDE) persistent store. Subsequent attempts to access the encrypted Paradox table fails unless an application first calls AddPassword to reestablish a password.


TSession::SaveConfigFile

TSession	See also

Writes the current information in the Borland Database Engine (BDE) persistent store from memory to the BDE configuration file on disk.

void __fastcall SaveConfigFile(void);

Description

Call SaveConfigFile to write any BDE configuration changes currently in memory to the BDE configuration file on disk. When the BDE is first initialized, the current BDE configuration file is read into persistent storage in memory. Applications can read or modify the configuration file in memory, but modification exist only in memory, not on disk.

For example, if an application defines a new BDE alias with AddAlias, the alias exists in memory only for as long as the BDE resides in memory. To store the new alias for later use by all applications that use the BDE, call SaveConfigFile. SaveConfigFile overwrites the disk image of the configuration file with the in-memory image of the persistent configuration file.

Note:	If a session’s ConfigMode property is cmSession, added aliases cannot be saved to the BDE configuration file.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


 TShape

Hierarchy	Properties	Methods	Events	See also

TShape represents a geometric shape that can be drawn on a form.

Unit

extctrls

Description

Add a TShape object to a form to draw a simple geometric shape on the form. TShape introduces properties to describe the pen used to outline the shape and the brush used to fill it.

If the shape is only part of the image of a TCustomControl object, use the methods of the control’s canvas instead.


TShape properties

TShape	Alphabetically	Legend

In TShape

Brush

Pen

Shape

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TShape properties

TShape	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Owner

Parent

ParentShowHint

Pen

Shape

ShowHint

Tag

Top

VCLComObject

Visible

Width

WindowProc


TShape::Brush

TShape	See also	Example

Specifies the color and pattern used for filling the shape control.

__property Graphics::TBrush* Brush = {read=FBrush, write=SetBrush};

Description

Read Brush to obtain the TBrush object that represents the color and pattern that fill the interior of the shape. Use the properties of Brush to change the color or pattern.

Set the Brush property to assign another TBrush object to the TBrush object maintained by TShape.


TShape.Pen
TShape::Pen

TShape	Example

Specifies the pen used to outline the shape control.

__property Graphics::TPen* Pen = {read=FPen, write=SetPen};

Description

Read Pen to obtain the TPen object that represents the color and style of the line used to outline the shape. Use the properties of Pen to change the color or style.

Set the Pen property to assign another TPen object to the TPen object maintained by TShape.


TShape::Shape

TShape	Example

Specifies the shape of the control.

enum TShapeType { stRectangle, stSquare, stRoundRect, stRoundSquare, stEllipse, stCircle };

__property TShapeType Shape = {read=FShape, write=SetShape, default=0};

Description

Set Shape to the geometric shape that should be drawn on the form. The Shape property has these possible values:

Value	Meaning

stCircle	The shape is a circle.

stEllipse	The shape is an ellipse.

stRectangle	The shape is a rectangle.

stRoundRect	The shape is a rectangle with rounded corners.

stRoundSquare	The shape is a square with rounded corners.

stSquare	The shape is a square.


TShape events

TShape	Alphabetically	Legend

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TShape events

TShape	By object	Legend

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TShape methods

TShape	Alphabetically

In TShape

~TShape

TShape

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TShape methods

TShape	By object

~TShape

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TShape

Update


TShape::TShape

TShape	See also

Creates an instance of TShape.

__fastcall virtual TShape(Classes::TComponent* AOwner);

Description

Do not call TShape directly to instantiate a TShape object at runtime. Instead, use the new keyword, passing an Owner argument that specifies the control responsible for freeing the shape. Shapes added to a form at design time are created automatically.

TShape allocates memory and initializes the Height and Width properties of the shape to 65.


TShape::~TShape

TShape	See also

Destroys of an instance of TShape.

__fastcall virtual ~TShape(void);

Description

Do not call ~TShape directly in an application. Instead, use the delete keyword when destroying a TShape object.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


TSharedImage

Hierarchy	Methods	See also

TSharedImage is the abstract base class for classes that contain images used for graphics objects.

Unit

graphics

Description

TSharedImage is used as a base class for classes that hold the internal representation of graphical images such as bitmaps and icons. TSharedImage is an abstract class. Its descendant classes are used internally by C++Builder graphics objects, and are automatically created by their associated graphics objects.


TSharedImage methods

TSharedImage	Alphabetically

In TSharedImage

~TSharedImage

TSharedImage

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TSharedImage methods

TSharedImage	By object

~TSharedImage

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TSharedImage


TSharedImage::TSharedImage

TSharedImage

Creates a new TSharedImage object.

__fastcall TSharedImage(void) : System::TObject() { }

Description

Do not instantiate a TSharedImage object. To add a shared image to a form, create an instance of a TSharedImage descendant using the new keyword.


TSharedImage::~TSharedImage

TSharedImage

Frees the memory associated with the TSharedImage object.

__fastcall virtual ~TSharedImage(void) { }

Description

Do not call ~TSharedImage directly. Instead, use the delete keyword on the object, which causes ~TSharedImage to be invoked automatically.


Hierarchy

TObject


TSmallIntArray

Hierarchy	Properties	Methods	See also

TSmallIntArray is a dynamically resizeable array of 16-bit integers.

Unit

mxarrays

Description

Use TSmallIntArray to represent an array of short integers when the number of elements in the array is unknown. For example, decision cubes use TSmallIntArray objects to represent the coordinates of a cell in the multidimensional cache of summary values.


TSmallIntArray properties

TSmallIntArray	Alphabetically	Legend

In TSmallIntArray

Items

Derived from TBaseArray

AutoSize

Capacity

CompareProc

Count

Duplicates

ItemSize

Limit

List

SortOrder


TSmallIntArray properties

TSmallIntArray	By object	Legend

AutoSize

Capacity

CompareProc

Count

Duplicates

Items

ItemSize

Limit

List

SortOrder


TSmallIntArray::Items

TSmallIntArray	See also

Lists the elements in the array.

__property short Items[int Index] = {read=GetItem, write=PutItem};

Description

Use Items to read or set the value of the element indicated by the Index parameter, where 0 specifies the first element in the array, 1 specifies the second parameter, and so on.


TSmallIntArray methods

TSmallIntArray	Alphabetically

In TSmallIntArray

~TSmallIntArray

Add

Assign

GetItem

PutItem

TSmallIntArray

Derived from TBaseArray

Clear

Delete

Exchange

FindItem

IndexOf

Insert

InsertAt

RemoveItem

Sort

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TSmallIntArray methods

TSmallIntArray	By object

~TSmallIntArray

Add

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

Exchange

FieldAddress

FindItem

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetItem

GetNamePath

IndexOf

InheritsFrom

InitInstance

Insert

InsertAt

InstanceSize

MethodAddress

MethodName

NewInstance

PutItem

RemoveItem

SafeCallException

Sort

TSmallIntArray


TSmallIntArray.Add

TSmallIntArray	See also

Adds a new element to the array.

int __fastcall Add(short Value);

Description

Call Add to add an item to the end of an unsorted array, or to the appropriate position in a sorted array. To insert an element at a specified position within the array, use the Insert method instead.

Note:	Add assumes that sorted arrays are sorted in ascending order. To use Add on an array where SortOrder is TS_DESCENDING, temporarily change the CompareProc property to a function that multiplies the value returned by CompareProc by -1.


TSmallIntArray::Assign

TSmallIntArray	See also

Copies the Items property of another TSmallIntArray object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to copy the array from another object. If the Source parameter is a TSmallIntArray object, Assign replaces the Items property with the array from the source array. Otherwise, Assign calls the inherited method which will assign values from any Source object that handles a TSmallIntArray in its AssignTo method.

Note:	Assign only changes the list of elements. It does not copy the AutoSize, Capacity, CompareProc, Duplicates, or SortOrder properties. If the AutoSize property is false, be sure that the value of Capacity is at least as big as the Count property of the source array. If the array is sorted, source items will appear in sorted order. If the Duplicates property is not dupAccept, duplicate elements will not be copied from the source array.


TSmallIntArray::TSmallIntArray

TSmallIntArray	See also

Creates an instance of TSmallIntArray.

__fastcall virtual TSmallIntArray(int itemcount, int dummy);

Description

Call TSmallIntArray indirectly, using the new keyword, to create and initialize a TSmallIntArray object. TSmallIntArray sets the Capacity property to Itemcount and ignores the dummy parameter.

TSmallIntArray also initializes the following properties:

•	ItemSize is set to 2 (the size of a small integer).

•	CompareProc is initialized to a function that returns the difference between two 16-bit integers.

•	AutoSize is set to true.

•	Count is set to 0.


TSmallIntArray::GetItem

TSmallIntArray	See also

Returns the integer at the indicated position.

HIDESBASE short __fastcall GetItem(int index);

Description

Call GetItem to obtain the value of an integer in the array. The Index parameter indicates the element of the array, where the first element has the index 0, the second element has the index 1, and so on.


TSmallIntArray::PutItem

TSmallIntArray	See also

Replaces the value of an element in the array.

HIDESBASE void __fastcall PutItem(int index, short value);

Description

Call PutItem to change the value of an integer to the value Value. Unlike the Insert method, PutItem does not add a new item to the array, but replaces the value of an existing element. The Index parameter indicates which element to change, where 0 specifies the first element, 1 specifies the second element, and so on.

Note:	Calling PutItem with Index set to the value of the Count property will add a new element to the end of the array. This is the only case where PutItem adds a new element instead of replacing an existing one.


TSmallIntArray::~TSmallIntArray

TSmallIntArray

~TSmallIntArray frees the memory associated with the TSmallIntArray object.

__fastcall virtual ~TSmallIntArray(void) { }

Description

Do not call ~TSmallIntArray directly. Instead, use the delete keyword on the object, which causes ~TSmallIntArray to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TBaseArray


TSmallIntField

Hierarchy	Properties	Methods	Events	See also

TSmallintField represents a signed 16-bit integer field in a dataset.

Unit

db

Description

Small-integer fields can hold values in the range -32768 to 32767, and are used to hold values that are signed 16-bit whole numbers.

TSmallIntField differs from its immediate ancestor TIntegerField only in the data type it represents. Except for the DataSize property, all of the properties, methods, and events are the same as those of TIntegerField, and provide functionality that is useful for managing the value and properties of an integral numeric field in a database.


TSmallIntField properties

TSmallIntField	Alphabetically	Legend

In TSmallIntField

DataSize

Derived from TIntegerField

AsFloat

AsInteger

AsString

AsVariant

MaxValue

MinValue

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TSmallIntField properties

TSmallIntField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TSmallIntField::DataSize

TSmallIntField	See also 	Example

Indicates the amount of memory needed to store the value of a small integer field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a small integer field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For small integer fields, DataSize is always 2. This is the size of 16-bit integer values in the database tables, not the size of the LongInt data type used to store and manipulate integer values by TSmallIntField.


TSmallIntField events

TSmallIntField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TSmallIntField events

TSmallIntField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TSmallIntField methods

TSmallIntField	Alphabetically

In TSmallIntField

~TSmallIntField

TSmallIntField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSmallIntField methods

TSmallIntField	By object

~TSmallIntField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TSmallIntField

Validate


TSmallIntField::TSmallIntField

TSmallIntField	See also

Creates an instance of a TSmallintField object.

__fastcall virtual TSmallintField(Classes::TComponent* AOwner);

Description

It is seldom necessary to create a TSmallIntField directly, because a small-integer field object is instantiated automatically for all small-integer fields in a dataset. When creating a TSmallIntField, use the new keyword.

After calling the parent object’s constructor, TSmallIntField sets

•	DataType to ftSmallint

•	MinValue to -32768

•	MaxValue to 32767


TSmallIntField::~TSmallIntField

TSmallIntField

~TSmallIntField frees the memory associated with the TSmallIntField object.

__fastcall virtual ~TSmallintField(void) { }

Description

Do not call ~TSmallIntField directly. Instead, use the delete keyword on the object, which causes ~TSmallIntField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField

TIntegerField


TSimpleEvent

Hierarchy	Properties	Methods	See also

TSimpleEvent represents an unnamed manual event object.

Unit

syncobjs

Description

Use TSimpleEvent to coordinate between threads that all have access to the same simple event object. TSimpleEvent can also be used in a single-threaded application to coordinate sections of code that respond to different asynchronous events such as Windows messages or user actions.

Because TSimpleEvent represents an unnamed event object, a single TSimpleEvent object must be within the scope of all code that uses it. To coordinate with code that is out of scope, or with other applications, use a named TEvent object.


TSimpleEvent properties

TSimpleEvent	Alphabetically	Legend

Derived from THandleObject

Handle

LastError


TSimpleEvent properties

TSimpleEvent	By object	Legend

Handle

LastError


TSimpleEvent methods

TSimpleEvent	Alphabetically

In TSimpleEvent

~TSimpleEvent

TSimpleEvent

Derived from TEvent

ResetEvent

SetEvent

WaitFor

Derived from THandleObject

Derived from TSynchroObject

Acquire

Release

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TSimpleEvent methods

TSimpleEvent	By object

~TSimpleEvent

Acquire

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Release

ResetEvent

SafeCallException

SetEvent

TSimpleEvent

WaitFor


TSimpleEvent::TSimpleEvent

TSimpleEvent	See also

Creates a Windows event object and instantiates a TSimpleEvent object to represent that event.

__fastcall TSimpleEvent(void);

Description

Call TSimpleEvent indirectly, using the new keyword, to create a TSimpleEvent object. TSimpleEvent creates a manual, unnamed Windows event object. The event starts out in an unset state.

The Handle property is initialized to the Windows handle for the event object.


TSimpleEvent::~TSimpleEvent

TSimpleEvent

Frees the memory associated with the TSimpleEvent object.

__fastcall virtual ~TSimpleEvent(void) { }

Description

Do not call ~TSimpleEvent directly. Instead, use the delete keyword on the object, which causes ~TSimpleEvent to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TSynchroObject

THandleObject

TEvent


TSocketDispatcher

Hierarchy	Properties	Methods	Events	See also

TSocketDispatcher manages server socket connections for a TCP/IP server that communicates using an IDispatch interface.

Unit

MIDASCon

Description

Add a TSocketDispatcher object to a form or data module to create an application server that implements an IDispatch interface using TCP/IP instead of DCOM. TSocketDispatcher listens for requests for a TCP/IP connection from a TMIDASConnection component, and establishes connections when requests are received.  Once a connection is established, TSocketDispatcher responds to messages from the TMIDASConnection component that represent invocations of the IDispatch interface.

When adding a socket dispatcher to an application server, the socket dispatcher should be put in a separate form or data module, rather than in the remote data module. In the same form or data module that contains the socket dispatcher, add a TSession component, and set its AutoSessionName property to true, so that the separate connection threads will each have their own session.

The form or data module that contains the socket dispatcher must be running to listen for connection requests from client applications. It can’t be launched from the client.

Note:	Application servers do not need to explicitly add a TSocketDispatcher so that they can connect to TMIDASConnection components in client applications.  C++Builder Client/Server ships with an executable called ScktSrvr.exe.  Run ScktSrvr on the server machine.  If the application server does not want to use the default port number (211), pass the port number the application server should use for listening for client connections as a command line argument.  If ScktSrvr.exe is running on the server machine, it will automatically launch the application server after it accepts client requests.


TSocketDispatcher properties

TSocketDispatcher	Alphabetically	Legend

In TSocketDispatcher

Socket

Derived from TCustomServerSocket

ThreadCacheSize

Derived from TAbstractSocket

Active

Port

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TSocketDispatcher properties

TSocketDispatcher	By object	Legend

Active

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Port

Socket

Tag

ThreadCacheSize

VCLComObject


TSocketDispatcher::Socket

TSocketDispatcher	See also

Describes the endpoint of the listening connection.

__property Scktcomp::TServerWinSocket* Socket = {read=FServerSocket};

Description

Use Socket to obtain

•	Information about the connections currently active on the server socket.

•	Information about the connection threads that are cached for use by the socket dispatcher.

•	Access to the Windows socket handle for the listening connection that is needed for Windows socket API calls.


TSocketDispatcher events

TSocketDispatcher	Alphabetically	Legend

Derived from TCustomServerSocket

OnClientDisconnect

OnGetSocket

OnThreadEnd

OnThreadStart

Derived from TCustomSocket

OnAccept

OnListen


TSocketDispatcher events

TSocketDispatcher	By object	Legend

OnAccept

OnClientDisconnect

OnGetSocket

OnListen

OnThreadEnd

OnThreadStart


TSocketDispatcher methods

TSocketDispatcher	Alphabetically

In TSocketDispatcher

~TSocketDispatcher

TSocketDispatcher

Derived from TCustomServerSocket

Derived from TAbstractSocket

Close

Open

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSocketDispatcher methods

TSocketDispatcher	By object

~TSocketDispatcher

AfterConstruction

Assign

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

SafeCallException

TSocketDispatcher


TSocketDispatcher::TSocketDispatcher

TSocketDispatcher	See also

Creates an instance of TSocketDispatcher.

__fastcall virtual TSocketDispatcher(Classes::TComponent* AOwner);

Description

Call TSocketDispatcher indirectly, using the new keyword, to create and initialize a server socket component at runtime. TSocketDispatcher objects placed at design time are created automatically.

After calling the parent class’s constructor, TSocketDispatcher

•	Allocates the TServerWinSocket object that encapsulates the Windows socket connection for the server socket.

•	Initializes the event and error dispatchers for the server socket.

•	Initializes ThreadCacheSize to 10.

•	Instructs the socket dispatcher to use a specialized thread object for client connections that reponds to IDispatch commands.


TSocketDispatcher::~TSocketDispatcher

TSocketDispatcher

~TSocketDispatcher frees the memory associated with the TSocketDispatcher object.

__fastcall virtual ~TSocketDispatcher(void) { }

Description

Do not call ~TSocketDispatcher directly. Instead, use the delete keyword on the object, which causes ~TSocketDispatcher to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TAbstractSocket

TCustomSocket

TCustomServerSocket


TSocketStream

Hierarchy	Properties	Methods	See also

The TSocketStream object reads or writes data packets over a TCP/IP connection.

Unit

MIDASCon

Description

TSocketStream is used internally by TMIDASConnection to pass information over a socket connection using an IDispatch interface.  Most applications will have no need to use TSocketStream directly.

TSocketStream is a memory stream that reads from and writes to an in-memory image of IDispatch commands and their return values, stored as OLE variants.  TSocketStream introduces new protected methods that pass the current contents of the in-memory image over the socket connection and that replace the in-memory image with results read from the socket connection.


TSocketStream properties

TSocketStream	Alphabetically	Legend

Derived from TCustomMemoryStream

Memory

Derived from TStream

Position

Size


TSocketStream properties

TSocketStream	By object	Legend

Memory

Position

Size


TSocketStream methods

TSocketStream	Alphabetically

In TSocketStream

~TSocketStream

TSocketStream

WaitForAction

Write

Derived from TMemoryStream

Clear

LoadFromFile

LoadFromStream

SetSize

Derived from TCustomMemoryStream

Read

SaveToFile

SaveToStream

Seek

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TSocketStream methods

TSocketStream	By object

~TSocketStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

SaveToFile

SaveToStream

Seek

SetSize

TSocketStream

WaitForAction

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TSocketStream::TSocketStream

TSocketStream	See also

TSocketStream creates an instance of TSocketStream.

Description

Most applications do not need to call the constructor for TSocketStream.  TMIDASConnection objects construct socket stream objects internally to handle IDispatch communication over the socket connection.  After calling the parent object’s constructor, TSocketStream associates the socket stream with the windows socket object that is passed as a parameter.  This windows socket object is the local endpoint of the socket connection between the client application and the server application.

Many of the methods of TSocketStream use the associated windows socket object to pass the current contents of the stream over the socket connection or to read new contents from the socket connection.


TSocketStream::WaitForAction

TSocketStream	See also

WaitForAction reads an instruction from the socket connection and performs the appropriate response.

Description

When implementing an application server, call WaitForAction from within a loop that continues while the socket connection is open. WaitForAction reads and responds appropriately to IDispatch messages sent by a TMIDASConnection component on the client side.


TSocketStream::Write

TSocketStream	See also

Write writes Count bytes from Buffer to the current position in the memory buffer and updates the current position by Count bytes.

Description

Most applications will not need to use the Write method of TSocketStream.  Socket Streams use write internally to prepare memory images that are then passed over the socket connection.


TSocketStream::~TSocketStream

TSocketStream

~TSocketStream frees the memory associated with the TSocketStream object. Do not call ~TSocketStream directly. Instead, use the delete keyword on the object, which causes ~TSocketStream to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TStream

TCustomMemoryStream

TMemoryStream


 TSpeedButton

Hierarchy	Properties	Methods	Events	See also

TSpeedButton is a button that is used to execute commands or set modes.

Unit

buttons

Description

Use TSpeedButton to add a button to a group of buttons in a form. TSpeedButton introduces properties that can be used to set graphical images that represent the different button states (selected, unselected, disabled and so on). Use other properties to specify multiple images or to rearrange the images and text on the button. TSpeedButton also introduces properties that allow speed buttons to work together as a group. Speed buttons are commonly grouped in panels to create specialized tool bars and tool palettes.

Note:	To create a speed button with a client-aligned glyph that covers the button's edges, add a 1-pixel margin around the button's top and left edges and a 3-pixel margin around its bottom and right edges. Do this by manually editing the bitmap specified by the Glyph property.


TSpeedButton properties

TSpeedButton	Alphabetically	Legend

In TSpeedButton

AllowAllUp

Down

Flat

Glyph

GroupIndex

Layout

Margin

NumGlyphs

Spacing

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TSpeedButton properties

TSpeedButton	By object	Legend

Align

AllowAllUp

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

Down

Enabled

Flat

Font

Glyph

GroupIndex

Height

Hint

Layout

Left

Margin

Name

NumGlyphs

Owner

Parent

ParentFont

ParentShowHint

ShowHint

Spacing

Tag

Top

VCLComObject

Visible

Width

WindowProc


TSpeedButton::AllowAllUp

TSpeedButton	See also	Example

Specifies whether all speed buttons in the group that contains this speed button can be unselected at the same time.

__property bool AllowAllUp = {read=FAllowAllUp, write=SetAllowAllUp, default=0};

Description

Use AllowAllUp with a group of buttons that belong to the same group. Speed buttons belong to the same group if they have the same value on their GroupIndex property. Buttons in the same group behave in a mutually exclusive fashion: when one button in the group is selected (down), all other buttons in the group become unselected (up). If AllowAllUp is true, all of the speed buttons in a group can be unselected at the same time. Clicking the single selected button in the group will deselect that button without selecting another. If AllowAllUp is false, exactly one of the buttons in the group must be selected at any time. Clicking a down button won't return the button to its up state.

Changing the value of the AllowAllUp property for one speed button in a group changes the AllowAllUp value for all buttons in the group.

Note:	If GroupIndex is zero, AllowAllUp has no effect.


TSpeedButton::Down

TSpeedButton	See also	Example

Specifies whether the button is selected (down) or unselected (up).

__property bool Down = {read=FDown, write=SetDown, default=0};

Description

Read Down to determine whether a speed button is selected. The Down property only applies if the GroupIndex property of the button is nonzero.

When GroupIndex is greater than 0, set Down to true to select a button. When the user clicks on a button in the unselected (up) state, the button is selected and Down is set to true. When the user clicks on a button in the selected (down) state, if AllowAllUp is true, the button becomes unselected and Down is set to false.

At design time, specify which button in a group is the initially selected button by setting the Down property of the selected button to true.

Note:	When GroupIndex is 0, buttons do not remain in the selected state when clicked.


TSpeedButton::Flat

TSpeedButton	See also

Determines whether the button has a 3D border that provides a raised or lowered look.

__property bool Flat = {read=FFlat, write=SetFlat, default=0};

Description

Set Flat to true to remove the raised border when the button is unselected and the lowered border when the button is clicked or selected. When Flat is true, use separate bitmaps for the different button states to provide visual feedback to the user about the button state.


TSpeedButton::Glyph

TSpeedButton	See also 	Example

Specifies the bitmap that appears on the speed button.

__property Graphics::TBitmap* Glyph = {read=GetGlyph, write=SetGlyph};

Description

Set Glyph to a bitmap object that contains the image that should appear on the face of the button. Bring up the Open dialog box from the Object Inspector to choose a bitmap file (with a .BMP extension), or specify a bitmap file at runtime.

Glyph can provide up to four images within a single bitmap. All images must be the same size and next to each other in a horizontal row. TSpeedButton displays one of these images depending on the state of the button.

Image position	Button state	Description

First	Up	This image appears when the button is unselected. If no other images exist in the bitmap, this image is used for all states.

Second	Disabled	This image usually appears dimmed to indicate that the button can't be selected.

Third	Clicked	This image appears when the button is clicked. If GroupIndex is 0, The Up image reappears when the user releases the mouse button.

Fourth	Down	This image appears when the button stays down indicating that it remains selected.

If only one image is present, TSpeedButton attempts to represent the other states by altering the image slightly for each state, although the Down state is always the same as the Up state.

If the bitmap contains multiple images, specify the number of images in the bitmap with the NumGlyphs property.

Note:	The lower left hand pixel of the bitmap is reserved for the “transparent” color. Any pixel in the bitmap which matches that lower left hand pixel will be transparent.


TSpeedButton::GroupIndex

TSpeedButton	See also	Example

Allows speed buttons to work together as a group.

__property int GroupIndex = {read=FGroupIndex, write=SetGroupIndex, default=0};

Description

Set GroupIndex to determine how the button behaves when clicked.

When GroupIndex is 0, the button behaves independently of all other buttons on the form. When the user clicks such a speed button, the button appears pressed (in its clicked state) and then returns to its normal up state when the user releases the mouse button.

When GroupIndex is greater than 0, the button remains selected (in its down state) when clicked by the user. When the user clicks a selected button, it returns to the up state, unless AllowAllUp is false. Setting the GroupIndex property of a single speed button to a value greater than 0 causes the button to behave as a two-state button when AllowAllUp is true.

Speed buttons with the same GroupIndex property value (other than 0), work together as a group. When the user clicks one of these buttons, it remains selected until the user clicks another speed button belonging to the same group. Speed buttons used in this way can present mutually exclusive choices to the user.


TSpeedButton::Layout

TSpeedButton	See also

Determines where the image or text appears on the speed button.

enum TButtonStyle { bsAutoDetect, bsWin31, bsNew };

__property TButtonLayout Layout = {read=FLayout, write=SetLayout, default=0};

Description

Set Layout to determine the position of the bitmap specified by the Glyph property or the text specified by the Caption property. These are the possible values:

Value	Meaning

blGlyphLeft	The image or caption appears near the left side of the button.

blGlyphRight	The image or caption appears near the right side of the button.

blGlyphTop	The image or caption appears near the top of the button.

blGlyphBottom	The image or caption appears near the bottom of the button.


TSpeedButton::Margin

TSpeedButton	See also

Specifies the number of pixels between the edge of the button and the image or caption drawn on its surface.

__property int Margin = {read=FMargin, write=SetMargin, default=-1};

Description

Use Margin to specify the indentation of the image specified by the Glyph property or the text specified by the Caption property. The edges that Margin separates depends on the Layout property. If Layout is blGlyphLeft, the margin appears between the left edge of the image or caption and the left edge of the button. If Layout is blGlyphRight, the margin separates the right edges. If Layout is blGlyphTop, the margin separates the top edges, and if Layout is blGlyphBottom, the margin separates the bottom edges.

If Margin is -1 then the image or text are centered on the button.


TSpeedButton::NumGlyphs

TSpeedButton	See also 	Example

Specifies the number of images specified in the Glyph property.

typedef Shortint TNumGlyphs;

__property TNumGlyphs NumGlyphs = {read=GetNumGlyphs, write=SetNumGlyphs, default=1};

Description

Set NumGlyphs to the number of images provided by the bitmap assigned to the Glyph property. All images must be the same size and next to each other in a row. The Glyph property can provide up to four images.


TSpeedButton::Spacing

TSpeedButton	See also

Determines where the image and text appear on a speed button.

__property int Spacing = {read=FSpacing, write=SetSpacing, default=4};

Description

Set Spacing to the number of pixels that should appear between the image specified in the Glyph property and the text specified in the Caption property.

If Spacing is a positive number, its value is the number of pixels between the image and text. If Spacing is 0, the image and text appear flush with each other. If Spacing is -1, the text appears centered between the image and the button edge.


TSpeedButton events

TSpeedButton	Alphabetically	Legend

Derived from TControl

OnClick

OnDblClick

OnMouseDown

OnMouseMove

OnMouseUp


TSpeedButton events

TSpeedButton	By object	Legend

OnDblClick

OnMouseDown

OnMouseMove

OnMouseUp

OnClick


TSpeedButton methods

TSpeedButton	Alphabetically

In TSpeedButton

~TSpeedButton

Click

TSpeedButton

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSpeedButton methods

TSpeedButton	By object

~TSpeedButton

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TSpeedButton

Update


TSpeedButton::Click

TSpeedButton	See also

Generates an OnClick event.

DYNAMIC void __fastcall Click(void);

Description

Call Click to generate an OnClick event. If the speed button has an OnClick event handler, Click allows an application to simulate a click on the button.


TSpeedButton::TSpeedButton

TSpeedButton	See also

Creates and initializes an instance of TSpeedButton.

__fastcall virtual TSpeedButton(Classes::TComponent* AOwner);

Description

Call TSpeedButton indirectly, using the new keyword, to create a speed button at runtime. Speed buttons placed on forms at design time are created automatically.

After calling the parent object’s constructor, TSpeedButton initializes the following values:

•	ControlStyle is set to [csCaptureMouse, csOpaque, csDoubleClicks].

•	Height and Width are both set to 25.

•	Layout is set to blGlyphLeft.

•	Margin is set to -1, and Spacing to 4.

•	ParentFont is set to true.


TSpeedButton::~TSpeedButton

TSpeedButton	See also

Destroys an instance of TSpeedButton.

__fastcall virtual ~TSpeedButton(void);

Description

Do not call ~TSpeedButton directly in an application. Instead, use the delete keyword.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


 TSplitter

Hierarchy	Properties	Methods	Events	See also	Example

TSplitter divides the client area of a form into resizable panes.

Unit

extctrls

Description

Add a splitter to a form between two aligned controls to allow users to resize the controls at runtime. The splitter sits between a control aligned to one edge of the form and the controls that fill up the rest of the client area. Give the splitter the same alignment as the control that is anchored to the edge of the form. When the user moves the splitter, it resizes the anchored control. This, in turn, changes the client area of the form, and the controls that fill up the rest of the client area resize accordingly.

Use each control on the form as a separate pane. After each pane is placed, place a splitter with the same alignment to allow that pane to be resized. The last pane to be placed on the form should be client-aligned, so that it resizes automatically to fill up the remaining space after all other panes are resized.


TSplitter properties

TSplitter	Alphabetically	Legend

In TSplitter

Beveled

MinSize

ResizeStyle

Derived from TGraphicControl

Canvas

Derived from TControl

Align

BoundsRect

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentColor

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TSplitter properties

TSplitter	By object	Legend

Align

Beveled

BoundsRect

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Height

Hint

Left

MinSize

Name

Owner

Parent

ParentColor

ResizeStyle

ShowHint

Tag

Top

VCLComObject

Visible

Width

WindowProc


TSplitter::Beveled

TSplitter	See also

Determines whether the splitter looks beveled along the edge that moves.

__property bool Beveled = {read=FBeveled, write=SetBeveled, default=1};

Description

Set Beveled to false to remove the beveled edges from the splitter. Set Beveled to true to give the edge a 3D beveled look.

The bevel on a splitter runs in a single direction only: along the edges the user moves to resize neighboring objects. Thus, if the Align property is alLeft or alRight, the vertical edges of the splitter are beveled. If the Align property is alTop or alBottom, the horizontal edges of the splitter are beveled.


TSplitter::MinSize

TSplitter	See also 	Example

Specifies the minimum size, in pixels, of the panes on either side of the splitter.

typedef int NaturalNumber;

__property NaturalNumber MinSize = {read=FMinSize, write=FMinSize, default=30};

Description

Set MinSize to provide a minimum size the splitter must leave when resizing its neighboring control.  For example, if the Align property is alLeft or alRight, the splitter can’t resize the regions to its left or right any smaller than MinSize pixels. If the Align property is alTop or alBottom, the splitter can’t resize the regions above or below it any smaller than MinSize pixels.

Note:	Always set MinSize to a value less than half the client width of its parent.  When MinSize is half the client width of the splitter’s parent, the splitter can’t move because to do so would be to resize one of the panes less than MinSize pixels.


TSplitter::ResizeStyle

TSplitter	See also 	Example

Specifies the effect of moving the splitter.

enum TResizeStyle { rsNone, rsLine, rsUpdate };

__property TResizeStyle ResizeStyle = {read=FResizeStyle, write=FResizeStyle, default=1};

Description

Use ResizeStyle to determine what happens when the user moves the splitter with the mouse. ResizeStyle can have one of the values in the following table:

Value	Meaning

rsNone	Moving the splitter with the mouse has no effect.

rsLine	A line is drawn indicating the new position of the splitter that would result if the user released the mouse at the current position. The splitter does not actually move and no controls are resized.

rsUpdate	The control against which the splitter is aligned is resized based on the current mouse position, and the splitter is moved to that position.


TSplitter events

TSplitter	Alphabetically	Legend

In TSplitter

OnCanResize

OnMoved

OnPaint


TSplitter events

TSplitter	By object	Legend

OnCanResize

OnMoved

OnPaint


TSplitter::OnCanResize

TSplitter	See also

Occurs when the user tries to move the splitter with the mouse.

typedef void __fastcall (__closure *TCanResizeEvent)(System::TObject* Sender, int &NewSize, bool &Accept);

__property TCanResizeEvent OnCanResize = {read=FOnCanResize, write=FOnCanResize};

Description

Write an OnCanResize event handler to conditionally prevent the user from resizing neighboring components using the splitter.

The NewSize parameter indicates the size the associated control will have if the splitter is allowed to perform the resize.  This value can be changed if the attempted resize can be partially allowed.  The Accept parameter indicates whether the resize should be permitted at all.  Set Accept to false to disallow any movement of the splitter.


TSplitter::OnMoved

TSplitter	See also 	Example

Occurs after the user has retiled the form using the splitter.

__property Classes::TNotifyEvent OnMoved = {read=FOnMoved, write=FOnMoved};

Description

Write an OnMoved event handler to take specific action when the user finishes dragging the edge of the neighboring control using the splitter. For example, after resizing a control on the edge of the form, use an OnMoved event handler to update the layout of the new client area of the form. Use the ClientRect property of the form to determine the new size remaining.


TSplitter::OnPaint

TSplitter	See also

Occurs when the splitter needs to draw itself.

__property Classes::TNotifyEvent OnPaint = {read=FOnPaint, write=FOnPaint};

Description

Write an OnPaint event handler to customize the appearance of the splitter. For example, use an OnPaint event handler to give a splitter the appearance of the splitters that appear in cool bar objects. Use the Canvas property as a drawing surface for painting the splitter. Use the ClientRect property to determine the coordinates of the canvas on which to paint the splitter.

When a splitter object receives a WM_PAINT message, it paints its background before generating the OnPaint event. If the Beveled property is true, the beveled appearance will also be added before the OnPaint event.  Most applications set Beveled to false when using the OnPaint event to customize the appearance of the splitter.


TSplitter methods

TSplitter	Alphabetically	Legend

In TSplitter

~TSplitter

CanResize

MouseDown

MouseMove

MouseUp

Paint

RequestAlign

StopSizing

TSplitter

Derived from TGraphicControl

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TSplitter methods

TSplitter	By object	Legend

~TSplitter

Assign

BeginDrag

BringToFront

CanResize

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

MouseDown

MouseMove

MouseUp

NewInstance

Paint

Perform

Refresh

RemoveComponent

Repaint

RequestAlign

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

StopSizing

TSplitter

Update


TSplitter::CanResize

TSplitter	See also

Determines how the splitter responds to mouse moves.

virtual bool __fastcall CanResize(int &NewSize);

Description

CanResize is called automatically when the user moves the mouse after pressing the mouse button on the splitter. The NewSize parameter indicates the size the associated control will have if the splitter is allowed to perform the resize. CanResize returns a Boolean that indicates whether the value specified by NewSize should be applied by redrawing the line (when ResizeStyle is rsLine) or resizing the associated control (when ResizeStyle is rsUpdate);

CanResize generates an OnCanResize event. Unless an OnCanResize event handler sets the value of NewSize and the return value, CanResize returns true without changing the NewSize parameter.

Note:	CanResize is not called if the value of ResizeStyle is rsNone when the user presses the mouse button.


TSplitter::TSplitter

TSplitter	See also 	Example

Creates an instance of TSplitter.

__fastcall virtual TSplitter(Classes::TComponent* AOwner);

Description

Call TSplitter indirectly, using the new keyword, to instantiate a splitter at runtime. TSplitter objects placed on forms at design time are created automatically.

TSplitter allocates memory for the TSplitter object and initializes

•	Beveled to true.

•	MinSize to 30.

•	Align to alLeft.

•	Width to 3.

•	Cursor to crHSplit.


TSplitter::MouseDown

TSplitter	See also

Dynamically locates the control that can be resized by the splitter.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseDown(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

After calling the parent class’s method, MouseDown locates the control that it is about to resize. Because this control is located dynamically, an application can delete or add aligned controls beside a splitter at runtime and the splitter will resize whichever control is currently beside it.


TSplitter::MouseMove

TSplitter	See also

Provides visual feedback of how the neighboring control would be resized.

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseMove(Classes::TShiftState Shift, int X, int Y);

Description

After calling the parent class’s method, MouseMove computes the new boundaries of the neighboring control and draws a line where the new edge would be. The control is not actually resized until the mouse is released.


TSplitter::MouseUp

TSplitter	See also

Resizes the neighboring control when the user releases the mouse.

enum TMouseButton { mbLeft, mbRight, mbMiddle };

enum Classes__1 { ssShift, ssAlt, ssCtrl, ssLeft, ssRight, ssMiddle, ssDouble };

typedef Set<Classes__1, ssShift, ssDouble> TShiftState;

DYNAMIC void __fastcall MouseUp(Controls::TMouseButton Button, Classes::TShiftState Shift, int X, int Y);

Description

After calling the inherited method, MouseUp resizes the neighboring control that was located when the mouse went down. After the control is resized, MouseUp generates an OnMoved event.


TSplitter::Paint

TSplitter 	See also

Draws the image of the splitter in response to paint messages.

virtual void __fastcall Paint(void);

Description

When the splitter receives WM_PAINT messages from its Parent, the splitter calls the Paint method. Paint draws the background color of the splitter, and if Beveled is true, draws a bevel along the moveable edges. After drawing the background and bevel, Paint generates an OnPaint event.


TSplitter::RequestAlign

TSplitter 	See also

Changes the cursor when the alignment of the splitter changes.

DYNAMIC void __fastcall RequestAlign(void);

Description

RequestAlign changes the cursor from crHSplit to crVSplit when the Align property changes to alBottom or alTop.  It changes the cursor from crVSplit to crHSplit when the Align property changes to any other value.

If the Cursor property is not crHSplit or crVSplit, RequestAlign has no effect.

Override RequestAlign to suppress the automatic cursor change or to implement a different association between alignment and the splitter’s cursor.


TSplitter::StopSizing

TSplitter	See also

Cleans up after the splitter has resized its neighboring control.

DYNAMIC void __fastcall StopSizing(void);

Description

This protected procedure is called when the user releases the mouse or hits the Escape key while using the splitter to resize a control. StopSizing makes sure that the resize line is no longer visible and generates an OnMoved event.


TSplitter::~TSplitter

TSplitter

Frees the memory associated with the TSplitter object.

__fastcall virtual ~TSplitter(void) { }

Description

Do not call ~TSplitter directly. Instead, use the delete keyword on the object, which causes ~TSplitter to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


TServerClientThread

Hierarchy	Properties	Methods	Events	See also

TServerClientThread is an execution thread used for a single connection to a client socket accepted by a Windows server socket.

Unit

scktcomp

Description

TServerWinSocket objects spawn TServerClientThread objects to handle separate client connections in separate execution threads. This allows server sockets to perform slow reading and writing operations with client sockets without adversely affecting the performance on other connections.

TServerClientThread introduces new properties to

•	Access the TServerWinSocket object that spawned the thread and the TServerClientWinSocket that is connected to the client socket.

•	Store and access thread-specific data.

•	Determine if the thread is stored in a thread cache maintained by the TServerWinSocket.

Applications that receive frequent client requests will want to derive a descendant class from TServerClientThread to handle reading and writing to separate clients. This is because TServerClientThread objects use the OnClientRead and OnClientWrite events of the associated server socket. These events are not thread-local.


TServerClientThread properties

TServerClientThread	Alphabetically	Legend

In TServerClientThread

ClientSocket

Data

KeepInCache

ServerSocket

Derived from TThread

FreeOnTerminate

Handle

Priority

Suspended

ThreadID


TServerClientThread properties

TServerClientThread	By object	Legend

ClientSocket

Data

FreeOnTerminate

Handle

KeepInCache

Priority

ServerSocket

Suspended

ThreadID


TServerClientThread::ClientSocket

TServerClientThread	See also

Specifies the TServerClientWinSocket object that uses the thread for all reading and writing over the socket connection.

__property TServerClientWinSocket* ClientSocket = {read=FClientSocket};

Description

Use ClientSocket to gain direct access to the Windows socket component that uses the thread. If ClientSocket is NULL, the thread is idle and available for re-use by another TServerClientWinSocket object. TServerClientThread uses ClientSocket to read from or write to the socket connection.


TServerClientThread::Data

TServerClientThread	See also

Points to application-specific data associated with the thread.

__property void * Data = {read=FData, write=FData};

Description

Use Data to associate information with the thread object. Data can store information in a thread-safe manner that would otherwise require the use of global variables.


TServerClientThread::KeepInCache

TServerClientThread	See also

Determines whether the thread should be kept in the thread cache maintained by ServerSocket.

__property bool KeepInCache = {read=FKeepInCache, write=FKeepInCache, nodefault};

Description

The TServerWinSocket that spawns server client threads for its connections to client sockets maintains a cache of server client threads for re-use. As server client threads are activated, the TServerWinSocket object sets the KeepInCache property to indicate whether the thread will fit in the thread cache.

When KeepInCache is true, FreeOnTerminate is set to false before the thread terminates, and the thread is left in the thread cache. When KeepInCache is false, the thread is freed when execution terminates.


TServerClientThread::ServerSocket

TServerClientThread	See also

Specifies the TServerWinSocket object that manages all the TServerClientThread objects for its client connections.

__property TServerWinSocket* ServerSocket = {read=FServerSocket};

Description

Use ServerSocket to get direct access to the listening Windows socket object that spawned the thread for a client connection it accepted. TServerClientThread passes events and errors to the appropriate event handlers assigned to ServerSocket. TServerClientThread adds itself to the cache of threads maintained by ServerSocket from its constructor, and removes itself when the thread terminates.


TServerClientThread events

TServerClientThread	Alphabetically

Derived from TThread

OnTerminate


TServerClientThread events

TServerClientThread	By object

OnTerminate


TServerClientThread methods

TServerClientThread	Alphabetically

In TServerClientThread

~TServerClientThread

TServerClientThread

Derived from TThread

Resume

Suspend

Terminate

WaitFor

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TServerClientThread methods

TServerClientThread	By object

~TServerClientThread

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Resume

SafeCallException

Suspend

Terminate

TServerClientThread

WaitFor


TServerClientThread::TServerClientThread

TServerClientThread	See also

Creates an instance of TServerClientThread.

__fastcall TServerClientThread(bool CreateSuspended, TServerClientWinSocket* ASocket);

Description

Call TServerClientThread to create an instance of TServerClientThread for a connection to a client socket, and add the thread to the cache maintained by the associated listening socket.

TServerClientThread

•	Initializes FreeOnTerminate to true.

•	Initializes Priority to tpHigher.

•	Initializes ClientSocket to the ASocket parameter and ServerSocket to ASocket::ServerWinSocket.

•	Starts the thread executing.

•	Adds the thread to the cache maintained by ServerSocket.

•	Sets the OnErrorEvent and OnSocketEvent event handlers of ClientSocket so that events are sent to ServerSocket.

•	Signals when initialization is complete and the thread is ready for reading from or writing to the client connection.


TServerClientThread::~TServerClientThread

TServerClientThread	See also

Destroys the server client thread object and releases the memory allocated to it.

__fastcall virtual ~TServerClientThread(void);

Description

Do not call ~TServerClientThread directly in an application. ServerClientThread objects are freed by the TServerWinSocket object that manages them.

~TServerClientThread frees the TServerClientWinSocket object that encapsulates the connection to the client socket before calling the parent object’s destructor.


Accessibility

Read-only


Hierarchy

TObject

TThread


TServerClientWinSocket

Hierarchy	Properties	Methods	Events	See also

TServerClientWinSocket describes the server endpoint of a socket connection to a client socket.

Unit

scktcomp

Description

TServerClientWinSocket is used by server socket components to manage the Windows socket API calls for the socket connection to an individual client socket. TServerClientWinSocket objects are created when a client socket connection is accepted by a listening server socket.

Applications can create and customize the properties of a TServerClientWinSocket object in an OnGetSocket event handler for a server socket component. Component writers can create descendants of TServerClientWinSocket that may be substituted for TServerClientWinSocket in the OnGetSocket event handler.


TServerClientWinSocket properties

TServerClientWinSocket	Alphabetically	Legend

In TServerClientWinSocket

ServerWinSocket

Derived from TCustomWinSocket

Addr

ASyncStyles

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle


TServerClientWinSocket properties

TServerClientWinSocket	By object	Legend

Addr

ASyncStyles

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle

ServerWinSocket


TServerClientWinSocket::ServerWinSocket

TServerClientWinSocket	See also

Describes the endpoint of the listening connection that accepted the connection to the client socket which is managed by this TServerClientWinSocket.

__property TServerWinSocket* ServerWinSocket = {read=FServerWinSocket};

Description

Use ServerWinSocket to gain access to the Windows socket object for the listening connection that spawned this TServerClientWinSocket. Use the ServerWinSocket to trigger events that can be handled by the event handlers of the server socket, to get execution threads from the cache maintained by the Windows server socket, or to get information about the other active connections accepted by the server socket.


TServerClientWinSocket events

TServerClientWinSocket	Alphabetically

Derived from TCustomWinSocket

OnErrorEvent

OnSocketEvent


TServerClientWinSocket events

TServerClientWinSocket	By object

OnSocketEvent

OnErrorEvent


TServerClientWinSocket methods

TServerClientWinSocket	Alphabetically

In TServerClientWinSocket

~TServerClientWinSocket

TServerClientWinSocket

Derived from TCustomWinSocket

Accept

Close

Connect

Disconnect

Listen

Lock

LookupName

LookupService

Open

Read

ReceiveBuf

ReceiveLength

ReceiveText

SendBuf

SendStream

SendStreamThenDrop

SendText

Unlock

Write

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TServerClientWinSocket methods

TServerClientWinSocket	By object

~TServerClientWinSocket

Accept

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

Connect

DefaultHandler

Disconnect

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

Listen

Lock

LookupName

LookupService

MethodAddress

MethodName

NewInstance

Open

Read

ReceiveBuf

ReceiveLength

ReceiveText

SafeCallException

SendBuf

SendStream

SendStreamThenDrop

SendText

TServerClientWinSocket

Unlock

Write


TServerClientWinSocket::TServerClientWinSocket

TServerClientWinSocket	See also

Creates and initializes an instance of TServerClientWinSocket.

__fastcall TServerClientWinSocket(int Socket, TServerWinSocket* ServerWinSocket);

Description

Call TServerClientWinSocket to create an instance of TServerClientWinSocket in the OnGetSocket event handler of a server socket component. The Socket parameter is the Windows socket handle for the accepted socket connection to a client socket. The ServerWinSocket parameter is the Windows socket object for the listening connection that accepted the connection to the client socket.

TServerClientWinSocket adds the new TServerClientWinSocket object to the list of connections maintained by the listening server socket. It then sets the OnSocketEvent event handler so that notifications from the connection to the client can be passed on to the server socket. After setting up the connection to the server socket, TServerClientWinSocket calls the parent object’s constructor.


TServerClientWinSocket::~TServerClientWinSocket

TServerClientWinSocket	See also

Destroys an instance of TServerClientWinSocket.

__fastcall virtual ~TServerClientWinSocket(void);

Description

Do not call ~TServerClientWinSocket directly. Instead, use the delete keyword on the object, which causes ~TServerClientWinSocket to be invoked automatically. Instances of TServerClientWinSocket are freed automatically when the connection is closed.

~TServerClientWinSocket removes the TServerClientWinSocket from the list of connections maintained by the listening windows socket.


Accessibility

Read-only


Hierarchy

TObject

TCustomWinSocket


 TServerSocket

Hierarchy	Properties	Methods	Events	See also

TServerSocket manages server socket connections for a TCP/IP server.

Unit

scktcomp

Description

Add a TServerSocket object to a form or data module to turn an application into a TCP/IP server. TServerSocket listens for requests for TCP/IP connections from other machines, and establishes connections when requests are received.

Note:	See the CHAT demo for an example of how to use TServerSocket.


TServerSocket properties

TServerSocket	Alphabetically	Legend

In TServerSocket

Socket

Derived from TCustomServerSocket

ServerType

ThreadCacheSize

Derived from TAbstractSocket

Active

Port

Service

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TServerSocket properties

TServerSocket	By object	Legend

Active

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Port

ServerType

Service

Socket

Tag

ThreadCacheSize

VCLComObject


TServerSocket::Socket

TServerSocket	See also

Specifies the TServerWinSocket object that describes the endpoint of the listening connection.

__property TServerWinSocket* Socket = {read=FServerSocket};

Description

Use Socket to obtain

•	Information about the connections currently active on the server socket.

•	Information about the connection threads that are cached for use by the server socket.

•	Access to the Windows socket handle for the listening connection that is needed for Windows socket API calls.


TServerSocket events

TServerSocket	Alphabetically	Legend

Derived from TCustomServerSocket

OnClientConnect

OnClientDisconnect

OnClientError

OnClientRead

OnClientWrite

OnGetSocket

OnGetThread

OnThreadEnd

OnThreadStart

Derived from TCustomSocket

OnAccept

OnListen


TServerSocket events

TServerSocket	By object	Legend

OnAccept

OnClientConnect

OnClientDisconnect

OnClientError

OnClientRead

OnClientWrite

OnGetSocket

OnGetThread

OnListen

OnThreadEnd

OnThreadStart


TServerSocket methods

TServerSocket	Alphabetically

In TServerSocket

~TServerSocket

TServerSocket

Derived from TAbstractSocket

Close

Open

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TServerSocket methods

TServerSocket	By object

~TServerSocket

AfterConstruction

Assign

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

Open

RemoveComponent

SafeCallException

TServerSocket


TServerSocket::TServerSocket

TServerSocket	See also

Creates an instance of TServerSocket.

__fastcall virtual TServerSocket(Classes::TComponent* AOwner);

Description

Call TServerSocket to create and initialize a server socket component at runtime. TServerSocket objects placed at design time are created automatically.

After calling the parent object’s constructor, TServerSocket

•	Allocates the TServerWinSocket object that encapsulates the Windows socket connection for the server socket.

•	Initializes the event and error dispatchers for the server socket.

•	Initializes ThreadCacheSize to 10.


TServerSocket::~TServerSocket

TServerSocket

~TServerSocket frees the memory associated with the TServerSocket object.

__fastcall virtual ~TServerSocket(void) { }

Description

Do not call ~TServerSocket directly. Instead, use the delete keyword on the object, which causes ~TServerSocket to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TAbstractSocket

TCustomSocket

TCustomServerSocket


TServerWinSocket

Hierarchy	Properties	Methods	Events	See also

TServerWinSocket describes the endpoint of a listening server socket connection.

Unit

scktcomp

Description

TServerWinSocket is used by server socket components to manage the Windows socket API calls for a TCP/IP listening connection. TServerWinSocket introduces new properties, events, and methods to manage multiple socket connections to different client sockets, and to generate or re-use TServerClientThread objects that allow each client connection to have its own execution thread.


TServerWinSocket properties

TServerWinSocket	Alphabetically	Legend

In TServerWinSocket

ActiveConnections

ActiveThreads

Connections

IdleThreads

ServerType

ThreadCacheSize

Derived from TCustomWinSocket

Addr

ASyncStyles

Connected

Data

Handle

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

SocketHandle


TServerWinSocket properties

TServerWinSocket	By object	Legend

ActiveConnections

ActiveThreads

Addr

ASyncStyles

Connected

Connections

Data

Handle

IdleThreads

LocalAddress

LocalHost

LocalPort

RemoteAddr

RemoteAddress

RemoteHost

RemotePort

ServerType

SocketHandle

ThreadCacheSize


TServerWinSocket::ActiveConnections

TServerWinSocket	See also

Indicates the number of connections to client sockets accepted by this listening socket that are currently open.

__property int ActiveConnections = {read=GetActiveConnections, nodefault};

Description

Use ActiveConnections to monitor the use of the server socket. ActiveConnections is the number of entries in the Connections array.


TServerWinSocket::ActiveThreads

TServerWinSocket	See also

Indicates the number of TServerClientThread objects currently in use by the socket connections listed in the Connections array.

__property int ActiveThreads = {read=GetActiveThreads, nodefault};

Description

Use ActiveThreads to monitor thread usage by the listening socket. If ActiveThreads is usually much higher than ThreadCacheSize, increasing ThreadCacheSize should improve performance. To determine whether ThreadCacheSize is too high, use the IdleThreads property.

When the ServerType property is stThreadBlocking, each client connection automatically spawns a thread which is added to the cache and counted by ActiveThreads.


TServerWinSocket::Connections

TServerWinSocket	See also

Lists all TServerClientWinSocket objects that represent open socket connections to client sockets which were accepted by this listening socket.

__property TCustomWinSocket* Connections[int Index] = {read=GetConnections};

Description

Use Connections with the ActiveConnections property to iterate over all open socket connections accepted by the listening socket. Each entry in the Connections array is a TServerClientWinSocket object, where an Index of 0 gives the first TServerClientWinSocket, an Index of 1 returns the second TServerClientWinSocket, and so on.

If ServerType is stThreadBlocking, the thread associated with each of the TServerClientWinSocket objects in the Connections array can be obtained using the GetClientThread method.


TServerWinSocket::IdleThreads

TServerWinSocket	See also

Indicates the number of unused TServerClientThread objects available in the cache.

__property int IdleThreads = {read=GetIdleThreads, nodefault};

Description

Use IdleThreads to monitor thread cache usage by the listening socket. If IdleThreads often very high, the thread cache is tying up a lot of unused memory storing extra threads. Monitor the ActiveThreads property to determine an appropriate value for ThreadCacheSize.

When the ServerType property is stThreadBlocking, each client connection automatically spawns a thread which is added to the cache. As the threads in the cache complete their execution, they become available for re-use, and are counted by IdleThreads. When there are more active threads than ThreadCacheSize, the extra threads are freed when they finish execution instead.


TServerWinSocket::ServerType

TServerWinSocket	See also

Specifies whether each connection accepted by the server socket is non-blocking, or if it is automatically given a separate execution thread.

__property TServerType ServerType = {read=FServerType, write=SetServerType, nodefault};

Description

Set ServerType to stThreadBlocking to automatically spawn a new thread for each socket connection accepted by the listening socket connection. When ServerType is stThreadBlocking, the TServerClientThread object for a connection generates OnClientRead or OnClientWrite events when the server socket needs to read or write.

Set ServerType to stNonBlocking to handle all reading and writing over socket connections accepted by the listening socket asynchronously. When ServerType is stNonBlocking, all client connections are handled in a single execution thread by default. OnClientRead or OnClientWrite events occur when the server socket needs to attend to I/O over one of the connections.

Use a non-blocking socket when reading and writing must be synchronized with client sockets.

Note:	When ServerType is stThreadBlocking, it is important that the OnClient event handlers contain thread-safe code.


TServerWinSocket::ThreadCacheSize

TServerWinSocket	See also

Indicates the number of TServerClientThread objects cached for re-use by new connections to client sockets.

__property int ThreadCacheSize = {read=FThreadCacheSize, write=SetThreadCacheSize, nodefault};

Description

When ServerType is stThreadBlocking, each new connection that is accepted by the server socket is given a separate execution thread. In order to improve performance, server sockets store the these threads in a cache rather than freeing them when the connection is closed. New connections can then reuse threads from the cache, rather than requiring the socket server to create a new thread every time a connection is accepted.

Set ThreadCacheSize to specify the number of threads that are cached for re-use. The ideal value for ThreadCacheSize depends on the number and frequency of client socket requests received by the server socket. If ThreadCacheSize is too low, the server socket will spend more time freeing and creating threads when client connections are accepted. If ThreadCacheSize is too high, the server socket may unnecessarily lock up the memory for threads that are never reused.


TServerWinSocket events

TServerWinSocket	Alphabetically

In TServerWinSocket

OnClientConnect

OnClientDisconnect

OnClientError

OnClientRead

OnClientWrite

OnGetSocket

OnGetThread

OnThreadEnd

OnThreadStart

Derived from TCustomWinSocket

OnErrorEvent

OnSocketEvent


TServerWinSocket events

TServerWinSocket	By object

OnClientConnect

OnClientDisconnect

OnClientError

OnClientRead

OnClientWrite

OnErrorEvent

OnGetSocket

OnGetThread

OnSocketEvent

OnThreadEnd

OnThreadStart


TServerWinSocket::OnClientConnect

TServerWinSocket	See also

Occurs when a client socket completes a connection accepted by the listening socket.

__property TSocketNotifyEvent OnClientConnect = {read=FOnClientConnect, write=FOnClientConnect};

Description

Write an OnClientConnect event handler to take specific action when a client socket completes the socket connection to a TServerClientWinSocket object. Depending on the service, this is the point when the socket should begin reading or writing.

The order of Windows server socket events leading up to OnClientConnect is as follows:

1	An OnSocketEvent event of type seListen occurs just before the Windows socket is opened for listening.

2	The listening Windows socket receives client requests in a listening queue. The listening socket accepts one of those requests, and receives a Windows socket handle for the new socket connection.

3	The listening socket generates an OnGetSocket event, passing in the Windows socket handle. If a TServerClientWinSocket object for the Windows socket handle was not created in the OnGetSocket event handler, the Windows socket creates one. The Windows socket continues to listen for other clients.

4	An OnSocketEvent event of type seAccept occurs, using the new TServerClientWinSocket object.

5	If ServerType is stThreadBlocking and no thread is available in the cache, an OnGetThread event occurs. If the OnGetThread event handler does not create a thread, the Windows socket object creates a TServerClientThread.

6	If ServerType is stThreadBlocking, an OnThreadStart event occurs as the thread begins execution.

7	The client completes the connection to the TServerClientWinSocket object and an OnClientConnect event occurs.

The Sender parameter is the TServerWinClient object that listens for client requests. The Socket parameter is the TServerClientWinSocket object that forms a connection to the client socket.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientConnect event handler is thread-safe. Use the GetClientThread method to access thread-specific information.

Note:	The OnClientConnect event handler for TServerWinSocket is also set when setting the OnClientConnect event handler of the associated TServerSocket.


TServerWinSocket::OnClientDisconnect

TServerWinSocket	See also

Occurs when one of the connections to a client socket is closed.

__property TSocketNotifyEvent OnClientDisconnect = {read=FOnClientDisconnect, write=FOnClientDisconnect};

Description

Write an OnClientDisconnect event handler to take specific action when the connection to a client socket is ending. The termination of a client request does not close the listening socket. The listening connection remains open for accepting new client connection requests.

The TServerClientWinSocket object associated with the client connection is freed after OnClientDisconnect. If ServerType is stThreadBlocking, OnThreadEnd occurs after OnClientDisconnect.

The Sender parameter is the TServerWinClient object that received the client request. The Socket parameter is the TServerClientWinSocket object that is ending a connection with the client socket.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientDisconnect event handler is thread-safe.Use the GetClientThread method to access thread-specific information.

Note:	The OnClientDisconnect event handler for TServerWinSocket is also set when setting the OnClientDisconnect event handler of the associated TServerSocket.


TServerWinSocket::OnClientError

TServerWinSocket	See also

Occurs when a failure is encountered when establishing, using, or terminating the socket connection to an individual client socket.

__property TSocketErrorEvent OnClientError = {read=FOnClientError, write=FOnClientError};

Description

Write an OnClientError event handler to respond to errors that arise with the connection to a client socket. Set the ErrorCode parameter to 0 if the OnClientError event handler successfully deals with the error condition, to prevent an ESocketError from being raised.

The Sender parameter is the TServerWinClient object that received the client request. The Socket parameter is the TServerClientWinSocket object that manages the connection to the client. The ErrorEvent parameter indicates what Socket was attempting to do when the error occurred. The ErrorCode parameter is the error code returned by the Windows socket API call.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientError event handler is thread-safe. Use the GetClientThread method to access thread-specific information.

Note:	The OnClientError event handler for TServerWinSocket is also set when setting the OnClientError event handler of the associated TServerSocket.


TServerWinSocket::OnClientRead

TServerWinSocket	See also

Occurs when the server socket should read information from a client socket.

__property TSocketNotifyEvent OnClientRead = {read=FOnClientRead, write=FOnClientRead};

Description

Write an OnClientRead event handler to read from the socket connection. Use a TWinSocketStream object or the methods of the Socket parameter to do the reading.

The Sender parameter is the TServerWinClient object that received the client request. The Socket parameter is the TServerClientWinSocket object that encapsulates the Windows socket connection.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientRead event handler is thread-safe. Use the GetClientThread method to access thread-specific information.

Note:	The OnClientRead event handler for TServerWinSocket is also set when setting the OnClientRead event handler of the associated TServerSocket.


TServerWinSocket::OnClientWrite

TServerWinSocket	See also

Occurs when the server socket should write information to a client socket.

__property TSocketNotifyEvent OnClientWrite = {read=FOnClientWrite, write=FOnClientWrite};

Description

Write an OnClientWrite event handler to write to the socket connection. Use a TWinSocketStream object or the methods of the Socket parameter to do the actual writing.

The Sender parameter is the TServerWinClient object that received the client request. The Socket parameter is the TServerClientWinSocket object that encapsulates the Windows socket connection.

Note:	If ServerType is stThreadBlocking, make sure that all code in an OnClientWrite event handler is thread-safe. Use the GetClientThread method to access thread-specific information.

Note:	The OnClientWrite event handler for TServerWinSocket is also set when setting the OnClientWrite event handler of the associated TServerSocket.


TServerWinSocket::OnGetSocket

TServerWinSocket	See also

Occurs when the server socket needs to create a new TServerClientWinSocket object to form the connection to a client socket.

__property TGetSocketEvent OnGetSocket = {read=FOnGetSocket, write=FOnGetSocket};

Description

Write an OnGetSocket event handler to create a specialized TServerClientWinSocket object to use in the connection represented by the Socket parameter. Return the new TServerClientWinSocket object in the ClientSocket parameter.

The Sender parameter is the TServerWinSocket object that received the client request. The Socket parameter is the Windows socket handle for the socket connection to the client socket.

Note:	The OnGetSocket event handler for TServerWinSocket is also set when setting the OnGetSocket event handler of the associated TServerSocket.


TServerWinSocket::OnGetThread

TServerWinSocket	See also

Occurs when the server socket needs to create a new execution thread for a connection to a client socket.

__property TGetThreadEvent OnGetThread = {read=FOnGetThread, write=FOnGetThread};

Description

Write an OnGetThread event handler to create a specialized descendant of TServerClientThread for the connection to the client socket. Create the new thread with the CreateSuspended parameter set to false, and return it in the SocketThread parameter. OnGetThread only occurs if there are no idle threads in the cache.

Most applications that use thread-blocking connections will want to create a new descendent of TServerClientThread in an OnGetThread event handler. This is because the default behavior of TServerClientThread uses the OnClientRead and OnClientWrite event handlers for reading and writing. These events occur on the server socket, which is not thread-local.

The Sender parameter is the TServerWinSocket object that received the client request. The ClientSocket parameter is the TServerClientWinSocket object that will communicate with the client socket.

Note:	The OnGetThread event handler for TServerWinSocket is also set when setting the OnGetThread event handler of the associated TServerSocket.


TServerWinSocket::OnThreadEnd

TServerWinSocket	See also

Occurs when a client socket connection is terminated and the associated thread finishes execution.

__property TThreadNotifyEvent OnThreadEnd = {read=FOnThreadEnd, write=FOnThreadEnd};

Description

Write an OnThreadEnd to take specific action when the thread for a client connection finishes execution. OnThreadEnd occurs after the OnClientDisconnect event.

The Sender parameter is the TServerWinSocket that received the client request. The Thread parameter is the thread that is finishing up.

Note:	The OnThreadEnd event handler for TServerWinSocket is also set when setting the OnThreadEnd event handler of the associated TServerSocket.


TServerWinSocket::OnThreadStart

TServerWinSocket	See also

Occurs when the execution thread for a connection to a client socket starts up.

__property TThreadNotifyEvent OnThreadStart = {read=FOnThreadStart, write=FOnThreadStart};

Description

Write an OnThreadStart to initialize the TServerClientThread for the connection to a single client socket. The Sender parameter is the TServerWinSocket that received the client request. The Thread parameter is the thread that is about to start execution.

Note:	The OnThreadStart event handler for TServerWinSocket is also set when setting the OnThreadStart event handler of the associated TServerSocket.


TServerWinSocket methods

TServerWinSocket	Alphabetically

In TServerWinSocket

~TServerWinSocket

Accept

Disconnect

GetClientThread

Listen

TServerWinSocket

Derived from TCustomWinSocket

Close

Connect

Lock

LookupName

LookupService

Open

ReceiveBuf

ReceiveLength

ReceiveText

SendBuf

SendStream

SendStreamThenDrop

SendText

Unlock

Write

Derived from TObject

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

Listen

MethodAddress

MethodName

NewInstance

SafeCallException


TServerWinSocket methods

TServerWinSocket	By object

~TServerWinSocket

Accept

AfterConstruction

BeforeDestruction

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Close

Connect

DefaultHandler

Disconnect

Dispatch

FieldAddress

Free

FreeInstance

GetClientThread

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

Listen

Lock

LookupName

LookupService

MethodAddress

MethodName

NewInstance

Open

ReceiveBuf

ReceiveLength

ReceiveText

SafeCallException

SendBuf

SendStream

SendStreamThenDrop

SendText

TServerWinSocket

Unlock

Write


TServerWinSocket::Accept

TServerWinSocket	See also

Accepts a connection to a client socket.

virtual void __fastcall Accept(int Socket);

Description

Accept is called automatically in response to notifications that a client socket is requesting a connection. The Socket parameter is the Windows socket handle for the listening connection.

Accept accepts the client connection request, obtaining the Windows socket handle for the client connection. It then generates an OnGetSocket event, passing this socket handle as an argument to any event handler. If a TServerClientWinSocket is not created by an OnGetSocket event handler, Accept creates a TServerClientWinSocket to represent the server endpoint of the accepted connection. Next, Accept obtains a running TServerClientThread, either by restarting a thread in the cache, obtaining one from an OnGetThread event, or creating a new TServerClientThread object. This new thread handles the connection to the client socket.

Accept is only called if the ASyncStyles property includes asAccept.


TServerWinSocket::TServerWinSocket

TServerWinSocket	See also

Creates an instance of TServerWinSocket from a Windows socket handle.

__fastcall TServerWinSocket(int ASocket);

Description

Call TServerWinSocket to create a Windows listening socket object. Windows listening socket objects are created automatically by the server socket component that uses them.

TServerWinSocket allocates the helper objects that manage the list of active client connections and the thread cache before calling the parent object’s constructor. TServerWinSocket also initializes the ASyncStyles property to [asAccept].


TServerWinSocket::~TServerWinSocket

TServerWinSocket	See also

Destroys an instance of TServerWinSocket.

__fastcall virtual ~TServerWinSocket(void);

Description

Do not call ~TServerWinSocket directly. Instead, use the delete keyword on the object, which causes ~TServerWinSocket to be invoked automatically. Unless the Windows socket object is not used by a server socket component, it is freed automatically by the socket component.

~TServerWinSocket frees the helper objects that manage the list of active client connections and the thread cache.


TServerWinSocket::Disconnect

TServerWinSocket	See also

Shuts down the socket connection represented by a Windows socket handle.

virtual void __fastcall Disconnect(int Socket);

Description

Disconnect is called by the Close method to terminate the socket connection.

Disconnect calls the Lock method to make sure the method is thread-safe. Then, it terminates all open connections to client sockets. Next it generates an OnSocketEvent of type seDisconnect. Finally, it closes the listening connection and calls Unlock to end the critical section started by Lock.


TServerWinSocket::GetClientThread

TServerWinSocket	See also

Returns the execution thread used by the client connection managed by the ClientSocket parameter.

TServerClientThread* __fastcall GetClientThread(TServerClientWinSocket* ClientSocket);

Description

Use GetClientThread to obtain access to the TServerClientThread for a particular client connection. GetClientThread allows an OnClient event handler to access thread-global information saved in the Data property of the thread.


TServerWinSocket::Listen

TServerWinSocket	See also

Opens a listening connection for a server socket.

HIDESBASE void __fastcall Listen(System::AnsiString &Name, System::AnsiString &Address, System::AnsiString &Service, Word Port, int QueueSize);

Description

Server socket components call Listen to open a listening connection.

Listen creates the windows socket that will make the listening connection, and binds the Windows internet socket address derived from the parameters to the socket. Listen then generates an OnSocketEvent of type seListen. Finally, Listen opens the socket as a listening connection with a queue that can hold QueueSize client requests, setting the Connected property to true.

The Name, Address, Service, and Port parameters are taken from the Host, Address, Service and Port properties of the server socket component. The QueueSize is set to 5 by TServerSocket.


Accessibility

Read-only


Hierarchy

TObject

TCustomWinSocket


 TStaticText

Hierarchy	Properties	Methods	Events	See also

TStaticText is a windowed control that displays text on a form.

Unit

stdctrls

Description

The TStaticText component functions like TLabel, except that it descends from TWinControl and therefore has a window handle. Use TStaticText instead of TLabel when the component’s accelerator key must belong to a windowed control—for example, on an ActiveX property page.


TStaticText properties

TStaticText	Alphabetically	Legend

Derived from TCustomStaticText

Alignment

AutoSize

BorderStyle

FocusControl

ShowAccelChar

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TStaticText properties

TStaticText	By object	Legend

Alignment

Align

AutoSize

BorderStyle

BoundsRect

Brush

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ControlCount

ControlState

Controls

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

FocusControl

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

ParentColor

ParentFont

ParentShowHint

Parent

ParentWindow

PopupMenu

ShowAccelChar

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TStaticText events

TStaticText	Alphabetically	Legend

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TStaticText events

TStaticText	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TStaticText methods

TStaticText	Alphabetically

In TStaticText

~TStaticText

TStaticText

Derived from TCustomStaticText

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TStaticText methods

TStaticText	By object

~TStaticText

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TStaticText

Update

UpdateControlState


TStaticText::TStaticText

TStaticText	See also

TStaticText creates a new TStaticText object.

__fastcall virtual TStaticText(Classes::TComponent* AOwner) : Stdctrls::TCustomStaticText(AOwner) { }

__fastcall TStaticText(HWND ParentWindow) : Stdctrls::TCustomStaticText(ParentWindow) { }

Description

Do not call TStaticText directly. Instead, use the keyword new, which returns an indirect reference to the new object. TStaticText objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the static-text object with an owner that is responsible for freeing the it. This is the most commonly used constructor syntax.

To embed the static-text object in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the static-text object is implemented as an ActiveX control.


TStaticText::~TStaticText

TStaticText

~TStaticText frees the memory associated with the TStaticText object.

__fastcall virtual ~TStaticText(void) { }

Description

Do not call ~TStaticText directly. Instead, use the delete keyword on the object, which causes ~TStaticText to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomStaticText


TStaticText example

TStaticText


TStringsAdapter

Hierarchy	Properties	Methods	See also

TStringsAdapter is a helper class used to allow a TStrings object to implement an IStrings interface for use with OLE.

Unit

axctrls

Description

To use a strings adapter to adapt a TStrings object so that it supports the IStrings interface, create the strings adapter by calling the GetOleStrings function, passing the TStrings object as a parameter.  Once the strings adapter is instantiated for a TStrings object, the StringsAdapter property of the TStrings object can be used to interact with the TStrings object through an IStrings interface.


TStringsAdapter properties

TStringsAdapter	Alphabetically	Legend

Derived from TAutoIntfObject

DispIID

DispIntfEntry

DispTypeInfo

Derived from TInterfacedObject

RefCount


TStringsAdapter properties

TStringsAdapter	By object	Legend

DispIID

DispIntfEntry

DispTypeInfo

RefCount


TStringsAdapter methods

TStringsAdapter	Alphabetically

In TStringsAdapter

~TStringsAdapter

TStringsAdapter

Derived from TAutoIntfObject

SafeCallException

Derived from TInterfacedObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TStringsAdapter methods

TStringsAdapter	By object

~TStringsAdapter

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TStringsAdapter


TStringsAdapter::TStringsAdapter

TStringsAdapter

TStringsAdapter constructs an instance of the string adapter control.

__fastcall TStringsAdapter(Classes::TStrings* Strings);

Description

Do not call the TStringsAdapter method directly. Instead, call the GetOleStrings function to adapt a TStrings object so that it supports the IStrings interface.


TStringsAdapter::~TStringsAdapter

TStringsAdapter

~TStringsAdapter frees the memory associated with the TStringsAdapter object.

__fastcall virtual ~TStringsAdapter(void) { }

description

Do not call ~TStringsAdapter directly. Instead, use the delete keyword on the object, which causes ~TStringsAdapter to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TInterfacedObject

TAutoIntfObject


 TStoredProc

Hierarchy	Properties	Methods	Events	See also

TStoredProc encapsulates a stored procedure on a database server.

Unit

dbtables

Description

Use a TStoredProc object when a client application must use a stored procedure on a database server. A stored procedure is a grouped set of statements, stored as part of a database server’s metadata (just like tables, indexes, and domains), that performs a frequently-repeated, database-related task on the server and passes results to the client.

Note:	Not all database servers support stored procedures. See a specific server’s documentation to determine if it supports stored procedures.

Many stored procedures require a series of input arguments, or parameters, that are used during processing. TStoredProc provides a Params property that enables an application to set these parameters before executing the stored procedure.

TStoredProc reuses the Params property to hold the results returned by a stored procedure. Params is an array of values. Depending on server implementation, a stored procedure can return either a single set of values, or a result set similar to the result set returned by a query.


TStoredProc properties

TStoredProc	Alphabetically	Legend

In TStoredProc

Overload

ParamBindMode

ParamCount

Params

Prepared

StmtHandle

StoredProcName

Derived from TDBDataSet

Database

DatabaseName

DBHandle

DBLocale

DBSession

Provider

SessionName

Derived from TBDEDataSet

CacheBlobs

CachedUpdates

CanModify

ExpIndex

Filter

Filtered

FilterOptions

Handle

KeySize

Locale

RecNo

RecordCount

RecordSize

UpdateObject

UpdateRecordTypes

UpdatesPending

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

DataSource

DefaultFields

Designer

EOF

FieldCount

FieldDefs

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TStoredProc properties

TStoredProc	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CacheBlobs

CachedUpdates

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Database

DatabaseName

DataSource

DBHandle

DBLocale

DBSession

DefaultFields

Designer

DesignInfo

EOF

ExpIndex

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Handle

KeySize

Locale

Modified

Name

Overload

Owner

ParamBindMode

ParamCount

Params

Prepared

Provider

RecNo

RecordCount

RecordSize

SessionName

State

StmtHandle

StoredProcName

Tag

UpdateObject

UpdateRecordTypes

UpdatesPending

VCLComObject


TStoredProc::Overload

TStoredProc	See also

Specifies which Oracle overloaded stored procedure to execute.

__property Word Overload = {read=FOverLoad, write=SetOverLoad, default=0};

Description

Use Overload to specify which overloaded stored procedure to execute on an Oracle server. An Oracle overloaded stored procedure is one that shares a name with one or more other stored procedures. Oracle distinguishes among overloaded stored procedures by assigning each procedure a unique numeric identifier. An application can specify this identifier using the Overload property.

By default, Overload is zero, which assumes there is no procedure overloading. For all servers except Oracle, do not change this value. If an application attempts to access an Oracle overloaded procedure without setting Overload, the Borland Database Engine (BDE) accesses the lowest numbered, or first, overloaded procedure on the server.

If Overload is 1, the BDE executes the first overloaded procedure on the server. If Overload is 2, it executes the second, and so on.

Note:	While Oracle overloaded procedures share names, their parameter lists are unique. An application must ensure that it passes the correct parameter list to an overloaded procedure.


TStoredProc::ParamBindMode

TStoredProc	See also	Example

Determines the order in which a component’s parameters are assigned to the parameter list for the stored procedure on the server.

__property TParamBindMode ParamBindMode = {read=FBindMode, write=FBindMode, default=0};

Description

Examine or set ParamBindMode to determine the order in which parameters in the Params property are matched to the parameters used by the stored procedure on the server. ParamBindMode can be one of the following:

Value	Ordering

pbByName	Parameters specified in the Params property are matched to identically named parameters on the server. This is the default.

pbByNumber	Parameters in Params are assigned one-by-one to the next available parameter on the server (i::e::, the first parameter in Params is assigned to the first parameter used by the stored procedure, and so on).

Whenever possible, ParamBindMode should be pbByName. This guarantees that parameters are matched to the correct parameters used by the stored procedure regardless of physical ordering in Params. At design time, the names of known parameters appear in the Parameters editor.

In some cases stored procedures on the server (for example, Informix) do not provide the Borland Database Engine (BDE) with parameter names. If parameter names as they exist on the server side are not known at design or runtime, it may be necessary to set ParamBindMode to pbByNumber. In this case, however, it is necessary to know the correct data type for each parameter in sequence. Otherwise an exception may be raised on execution.


TStoredProc::ParamCount

TStoredProc	See also 	Example

Indicates the number of parameters for the stored procedure component.

__property Word ParamCount = {read=GetParamsCount, nodefault};

Description

Examine ParamCount to determine the number of parameters currently stored in the Params property.


TStoredProc::Params

TStoredProc	See also 	Example

Stores the input and output parameters for a stored procedure.

__property TParams* Params = {read=FParams, write=SetParamsList};

Description

Access Params at runtime to set input parameter names, values, and data types dynamically (at design time use the Parameters editor to set parameter information). Params is an array of parameter values.

An application can also access Params after executing a stored procedure to retrieve the output parameters returned to the procedure by the server.


TStoredProc::Prepared

TStoredProc	See also	Example

Determines whether or not a stored procedure is prepared for execution.

__property bool Prepared = {read=FPrepared, write=SetPrepare, nodefault};

Description

Examine Prepared to determine if a stored procedure is already prepared for execution. If Prepared is true, the stored procedure is prepared, and if Prepared is false, the procedure is not prepared. A stored procedure must be prepared before it can be executed.

Note:	C++Builder automatically prepares a stored procedure if it is unprepared when the application calls ExecProc. After execution, C++Builder automatically unprepares the stored procedure. If a procedure will be executed a number of times, it is more efficient for the application to prepare the stored procedure once, and unprepare it when it is no longer needed.

An application can change the current setting of Prepared to prepare or unprepare a stored procedure. If Prepared is true, setting it to false calls the Unprepare method to unprepare the stored procedure. If Prepared is false, setting it to true calls the Prepare method to prepare the procedure. Generally, however, it is better programming practice to call Prepare and Unprepare directly. These methods automatically update the Prepared property.


TStoredProc::StmtHandle

TStoredProc

Identifies the Borland Database Engine (BDE) statement handle for the stored procedure.

__property Bde::hDBIStmt StmtHandle = {read=FStmtHandle};

Description

Retrieve StmtHandle if an application makes a direct call to the BDE, bypassing the methods of TStoredProc. Some BDE API calls require a statement handle as a parameter. Under all other circumstances an application does not need to access this property.


TStoredProc::StoredProcName

TStoredProc	See also	Example

Identifies the name of the stored procedure on the server for which this object is an encapsulation.

__property System::AnsiString StoredProcName = {read=FProcName, write=SetProcName};

Description

Set StoredProcName to specify the name of the stored procedure to call on the server. If StoredProcName does not match the name of an existing stored procedure on the server, then when the application attempts to prepare the procedure prior to execution, an exception is raised.


TStoredProc events

TStoredProc	Alphabetically	Legend

Derived from TBDEDataSet

OnServerYield

OnUpdateError

OnUpdateRecord

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TStoredProc events

TStoredProc	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnServerYield

OnUpdateError

OnUpdateRecord


TStoredProc methods

TStoredProc	Alphabetically

In TStoredProc

~TStoredProc

CopyParams

DescriptionsAvailable

ExecProc

GetResults

ParamByName

Prepare

TStoredProc

UnPrepare

Derived from TDBDataSet

CheckOpen

CloseDatabase

OpenDatabase

Derived from TBDEDataSet

ApplyUpdates

BookmarkValid

Cancel

CancelUpdates

CommitUpdates

CompareBookmarks

ConstraintCallBack

DisableConstraints

EnableConstraints

FetchAll

GetCurrentRecord

GetIndexInfo

Locate

Lookup

RevertRecord

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Post

Prior

Refresh

Resync

SetFields

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TStoredProc methods

TStoredProc	By object

~TStoredProc

ActiveBuffer

Append

AppendRecord

ApplyUpdates

Assign

BookmarkValid

Cancel

CancelUpdates

CheckBrowseMode

CheckOpen

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CloseDatabase

CommitUpdates

CompareBookmarks

ConstraintCallBack

ControlsDisabled

CopyParams

CursorPosChanged

DefaultHandler

Delete

DescriptionsAvailable

DestroyComponents

Destroying

DisableConstraints

DisableControls

Dispatch

Edit

EnableConstraints

EnableControls

ExecProc

FetchAll

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindLast

FindNext

FindPrior

First

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetResults

GotoBookmark

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

Last

Locate

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

OpenDatabase

ParamByName

Post

Prepare

Prior

Refresh

RemoveComponent

Resync

RevertRecord

SafeCallException

SetFields

Translate

TStoredProc

UnPrepare

UpdateCursorPos

UpdateRecord

UpdateStatus


TStoredProc::CopyParams

TStoredProc	See also	Example

Copies a stored procedure’s parameters into another parameter list.

void __fastcall CopyParams(TParams* Value);

Description

Call CopyParams to copy this stored procedure’s parameters into a separate parameter list object. Value is the parameter list into which to assign this stored procedure’s parameters. Value can be the parameter list of another stored procedure. For example:

StoredProc1->CopyParams(StoredProc2->Params);

If the stored procedure is not prepared when an application calls CopyParams, CopyParams calls Prepare before assigning the parameters to the target parameters list, and then calls UnPrepare to return the stored procedure to its previous state.


TStoredProc::TStoredProc

TStoredProc	See also

Creates an instance of a stored procedure component.

__fastcall virtual TStoredProc(Classes::TComponent* AOwner);

Description

Call TStoredProc to instantiate a stored procedure declared in an application. TStoredProc calls its parent object’s constructor constructor, creates an empty parameter list for the newly instantiated stored procedure, and initializes its parameter, server, and record buffers to NULL.


TStoredProc::DescriptionsAvailable

TStoredProc	See also	Example

Determines if parameter information is available from the stored procedure on the server.

bool __fastcall DescriptionsAvailable(void);

Description

Call DescriptionsAvailable to determine if a stored procedure on a server can return parameter information to the application. If DescriptionsAvailable returns true, parameter information is available from the server. If DescriptionsAvailable returns false, parameter information is not available.

Note:	If DescriptionsAvailable returns false, the application must still provide correct parameter information to the stored procedure on the server. It is up to the application developer to know the necessary parameters at design time.


TStoredProc::~TStoredProc

TStoredProc	See also

Destroys the instance of a stored procedure.

__fastcall virtual ~TStoredProc(void);

Description

Do not call ~TStoredProc directly. Instead call Free to verify that the stored procedure is not already freed before calling ~TStoredProc. ~TStoredProc disconnects from the server, frees the parameter list, and calls its parent object’s destructor destructor.


TStoredProc::ExecProc

TStoredProc	See also 	Example

Executes the stored procedure on the server.

void __fastcall ExecProc(void);

Description

Call ExecProc to execute a stored procedure on the server. Before calling ExecProc:

1	Provide any input parameters in the Params property. At design time, a developer can provide parameters using the Parameters editor. At runtime an application must access Params directly.

2	Call Prepare to bind the parameters.

If a stored procedure returns output parameters, they are stored in the Params property when ExecProc returns control to the application. An application can access the output parameters by indexing into the Params list, or by using the ParamByName method.

Tip:	If an application is only interested in the result set returned by a stored procedure, call StoredProc::Open or set its Active property to true.


TStoredProc::GetResults

TStoredProc	See also 	Example

Returns the output parameter values from a Sybase stored procedure.

void __fastcall GetResults(void);

Description

Call GetResults to force a Sybase stored procedure to return its result set, if any, to the client. For stored procedures on all other servers, result sets are automatically flushed to the client, but Sybase stored procedures do not return a result set until the cursor is positioned at the end of the set. GetResults forces the cursor to the end of the set.

If a Sybase stored procedure returns a result set and output parameters in response to GetResults, the output parameters are stored in the Params property. An application can access the output parameters by indexing into the Params list, or by using the ParamByName method.

Tip:	If an application is only interested in the result set returned by a stored procedure, call TStoredProc::Open or set its Active property to true.


TStoredProc::ParamByName

TStoredProc	See also 	Example

Accesses parameter information based on a specified parameter name.

TParam* __fastcall ParamByName(const System::AnsiString Value);

Description

Call ParamByName to return parameter information for a specific parameter based on its name. Value is the name of the parameter for which to retrieve information. Typically ParamByName is used to set an input parameter’s value at runtime, or to retrieve the value of an output parameter. For example, the following statement retrieves the current value of a parameter called “Contact” into an edit box:


TStoredProc::Prepare

TStoredProc	See also 	Example

Prepares a stored procedure for execution.

void __fastcall Prepare(void);

Description

Call Prepare to bind a stored procedure’s parameters before calling ExecProc to execute the procedure. Prepare readies a stored procedure’s parameters, initializes the Borland Database Engine (BDE), and informs the server of the stored procedure’s readiness. These steps allocate system resources and optimize the query for server performance.

Note:	If an application attempts to execute a stored procedure that has not been prepared, C++Builder automatically prepares the procedure before executing it, and then unprepares it when execution is complete. If a stored procedure will be executed more than once, it is more efficient for an application to call Prepare explicitly once to avoid repeated and unnecessary preparing and unpreparing of the stored procedure, and then call UnPrepare when the stored procedure is no longer needed.


TStoredProc::UnPrepare

TStoredProc	See also	Example

Frees the resources allocated for a previously prepared stored procedure.

void __fastcall UnPrepare(void);

Description

Call UnPrepare to free the resources allocated for a previously prepared stored procedure on the server and client sides.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet

TBDEDataSet

TDBDataSet


TStream

Hierarchy	Properties	Methods	See also

TStream is the base class type for objects that can read from or write to various kinds of storage media, such as disk files, dynamic memory, and so on.

Unit

classes

Description

Use specialized stream objects to read from, write to, or copy information stored in a particular medium. Each descendant of TStream implements methods for transferring information to and from a particular storage medium, such as a disk file, dynamic memory, and so on.  In addition to methods for reading, writing, and copying bytes to and from the stream, stream objects permit applications to seek to an arbitrary position in the stream. Properties of TStream provide information about the stream, such as its size and the current position in the stream.

TStream also introduces methods that work in conjunction with components and filers for loading and saving components in simple and inherited forms. These methods are called automatically by global routines that initiate component streaming. They can also be called directly to the initiate the streaming process. Note, however, that component streaming always involves two additional objects:

•	A component object that is passed as a parameter to the stream’s methods.

•	A filer object that is automatically created by the stream, and associated with the stream.

TStream cannot be instantiated; it relies on pure virtual methods that must be overridden in descendant classes. Descendant stream objects, such as memory and file streams used for component streaming, are created automatically by the global functions ReadComponentRes and WriteComponentRes. For streaming other kinds of information, choose a descendant class according to the specific data and storage needs.


TStream properties

TStream	Alphabetically

In TStream

Position

Size


TStream properties

TStream	By object

Position

Size


TStream::Position

TStream	See also

Indicates the current offset into the stream for reading and writing.

__property int Position = {read=GetPosition, write=SetPosition, nodefault};

Description

Use Position to obtain the current position of the stream. This is the number of bytes from the beginning of the streamed data.


TStream::Size

TStream	See also

Indicates the size in bytes of the stream.

__property int Size = {read=GetSize, write=SetSize, nodefault};

Description

Use Size to find the size of the stream. Size is used internally in routines that read and write to and from the stream. Setting the Size property of TStream does nothing. Some descendants of TStream override this property to allow applications to change the size of the resource accessed using the stream.


TStream methods

TStream	Alphabetically	Legend

In TStream

~TStream

CopyFrom

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

Seek

SetSize

TStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStream methods

TStream	By object	Legend

~TStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

Seek

SetSize

TStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TStream::CopyFrom

TStream 	Example

Copies a specified number of bytes from one stream to another.

int __fastcall CopyFrom(TStream* Source, int Count);

Description

Use CopyFrom to copy data to the stream from a different stream. Using CopyFrom eliminates the need for the user to create, read into, write from, and free a buffer when copying data.

CopyFrom copies Count bytes from the stream specified by Source into the stream. It then moves the current position by Count bytes, and returns the number of bytes copied.

If Count is 0, CopyFrom sets Source position to 0 before reading and then copies the entire contents of Source into the stream. If Count is greater than or less than 0, CopyFrom reads from the current position in Source.


TStream::Read

TStream	See also

Introduces a pure virtual method responsible for reading from the stream.

virtual int __fastcall Read(void *Buffer, int Count) = 0;

Description

Each descendant stream object defines a Read method that reads data from its particular storage medium (such as memory or a disk file).

Read is used in cases where the number of bytes to read from the stream is not necessarily fixed.

All the other data-reading methods of a stream (ReadBuffer, ReadComponent) call Read to do their actual reading.


TStream::ReadBuffer

TStream	See also

Reads bytes from the stream into Buffer.

void __fastcall ReadBuffer(void *Buffer, int Count);

Description

Use ReadBuffer to read Count bytes from the stream into a buffer in cases where the number of bytes is known and fixed, for example when reading in structures. ReadBuffer is used internally for loading from a stream and copying from a stream.

ReadBuffer calls Read to do the actual reading. If Count bytes cannot be read from the stream, an EReadError exception is thrown.


TStream::ReadComponent

TStream	See also

Initiates the streaming of components and their properties.

TComponent* __fastcall ReadComponent(TComponent* Instance);

Description

ReadComponent is called indirectly by the global routine ReadComponentRes, by the ReadComponentRes method, or it can be called directly to initiate component streaming.

ReadComponent reads data values from the stream and assigns them to Instance’s properties. It then constructs a reader object and calls the reader’s ReadRootComponent method to read Instance’s property values and construct child objects defined in the stream as children of the Instance. ReadComponent returns the component.

If Instance is NULL, ReadComponent constructs a component based on the type information in the stream and returns the newly-constructed component.


TStream::ReadComponentRes

TStream	See also

Reads components and their properties from a stream in a Windows resource file format.

TComponent* __fastcall ReadComponentRes(TComponent* Instance);

Description

ReadComponentRes is called automatically by the global routine ReadComponentResFile. It can also be called directly if the current position of the stream points to a component written using the WriteComponentRes method.

ReadComponentResFile creates a file stream object which then calls its ReadComponentRes method.

ReadComponentRes first calls the ReadResHeader method to read a resource header from the stream. If the stream does not contain a resource header at the current position, ReadResHeader will throw an EInvalidImage exception. ReadComponentRes then calls ReadComponent to read the properties that must be set on Instance.


TStream::ReadResHeader

TStream	See also

Reads a Windows resource-file header from the stream.

void __fastcall ReadResHeader(void);

Description

Do not call ReadResHeader directly. It is called automatically by ReadComponentRes before reading a component from a resource file.

After reading the resource-file header, ReadResHeader moves the current position of the stream to just beyond the header. If the stream does not contain a valid resource-file header, ReadResHeader raises an EInvalidImage exception.


TStream::Seek

TStream

Introduces a pure virtual method for moving to a specified position in the streamed resource.

virtual int __fastcall Seek(int Offset, Word Origin) = 0;

Description

Each descendant stream object defines a Seek method that moves the current position of the stream in its particular storage medium (such as memory or a disk file).

The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value	Meaning

soFromBeginning	Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.

soFromCurrent	Offset is from the current position in the resource. Seek moves to Position + Offset.

soFromEnd	Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Seek is called by the Position and Size properties.


TStream::SetSize

TStream

Provides a placeholder for a method to change the size of the streamed resource.

virtual void __fastcall SetSize(int NewSize);

Description

SetSize does nothing in TStream. Descendant stream classes can override this method to set the Size property of their objects. SetSize is the write procedure for the Size property.

Note:	SetSize is introduced in TStream, even though it does nothing, because it is not possible to change the definition of a property in a descendent class. SetSize must therefore be introduced when Size is introduced.


TStream::Write

TStream	See also

Introduces a pure virtual method for writing to the stream.

virtual int __fastcall Write(const void *Buffer, int Count) = 0;

Description

Each descendant stream object defines a Write method that writes data to its particular storage medium (such as memory or a disk file). All the other data-writing methods of a stream (WriteBuffer, WriteComponent) call Write to do their actual writing.


TStream::WriteBuffer

TStream	See also

Writes Count bytes from Buffer onto the stream and advances the current position of the stream by Count bytes.

void __fastcall WriteBuffer(const void *Buffer, int Count);

Description

Use WriteBuffer to save data to a stream. WriteBuffer and ReadBuffer are used in cases where the number of bytes is known and required, for example when reading in structures. Use WriteBuffer for standard file I/O streaming.

WriteBuffer is used internally for writing to a stream and copying from a stream. It is used by other objects, such as strings and lists, for writing strings to a buffer.

WriteBuffer calls Write to handle the actual writing. If the stream fails to write all the requested bytes, an EWriteError exception is thrown.


TStream::WriteComponent

TStream	See also

Initiates the writing of components and their properties to a stream.

void __fastcall WriteComponent(TComponent* Instance);

Description

WriteComponent is used internally in the C++Builder component streaming system, but can also be called directly when writing components to memory streams or database blobs.

WriteComponent constructs a writer object and calls its WriteRootComponent method to write the component specified by Instance, and its owned objects, to the stream.


TStream::WriteComponentRes

TStream	See also

Writes components and their properties to a stream from a Windows resource file format.

void __fastcall WriteComponentRes(const System::AnsiString ResName, TComponent* Instance);

Description

WriteComponentRes is used internally in the C++Builder streaming system, but can also be called directly when sending data to other applications on disk. WriteComponentRes is used for streaming components that need data, such as a bitmap, or icon to be stored specifically in a Windows resource-file format.

WriteComponentRes calls WriteDescendentRes, passing in NULL as the Ancestor. Therefore, WriteDescendentRes initiates the remainder of the streaming process for a component that, in this case, is not a descendant.

To read a component written with WriteComponentRes, call the ReadComponentRes method.


TStream::WriteDescendent

TStream	See also

Streams components and their properties in inherited forms.

void __fastcall WriteDescendent(TComponent* Instance, TComponent* Ancestor);

Description

Do not call WriteDescendent directly. WriteDescendent is called automatically by WriteComponent.

WriteDescendent constructs a writer object, then calls the writer object's WriteDescendent method to write the component passed in Instance to the stream. Instance is either an inherited form descended from Ancestor or NULL. However, WriteDescendent is never used to write owned components, only to initiate streaming on the root component.


TStream::WriteDescendentRes

TStream	See also

Streams components and their properties in inherited forms.

void __fastcall WriteDescendentRes(const System::AnsiString ResName, TComponent* Instance, TComponent* Ancestor);

Description

Do not call WriteDescendentRes directly. WriteDescendentRes is called automatically by WriteComponentRes.

WriteDescendentRes writes a standard Windows resource-file header to the stream, using the resource name passed in ResName as the name of the resource. It then calls WriteDescendent to write Instance to the stream as a descendant of Ancestor.


TStream::TStream

TStream

Creates a new TStream object.

__fastcall TStream(void) : System::TObject() { }

Description

Do not create instances of TStream. TStream relies on pure abstract methods that must be implemented in descendant classes.


TStream::~TStream

TStream

~TStream frees the memory associated with the TStream object.

__fastcall virtual ~TStream(void) { }

Description

Do not call ~TStream directly. Instead, use the delete keyword on the object, which causes ~TStream to be invoked automatically.


Scope

Protected


Hierarchy

TObject


TStream example

TStream


TStringGridStrings

Hierarchy	Properties	Methods	See also

TStringGridStrings maintains a list of the strings that appear in the cells of a string grid.

Unit

grids

Description

Do not use TStringGridStrings directly in an application. It is tailored to work with a TStringGrid object, and is created by the string grid to represent the strings (and associated objects) in a row or column of the grid.


TStringGridStrings properties

TStringGridStrings	Alphabetically	Legend

In TStringGridStrings

Count

Objects

Strings

Derived from TStrings

Capacity

CommaText

Names

StringsAdapter

Text

Values


TStringGridStrings properties

TStringGridStrings	By object	Legend

Capacity

CommaText

Count

Names

Objects

StringsAdapter

Strings

Text

Values


TStringGridStrings::Count

TStringGridStrings	See also

Indicates the number of entries in the Strings property array.

__property int Count = {read=GetCount, nodefault};

Description

Use Count to determine the number of strings managed by the instance of TStringGridStrings. If the TStringGridStrings object represents the strings in a row of the grid, Count is the number of columns in the grid. If the TStringGridStrings object represents the strings in a column of the grid, Count is the number of rows in the grid.


TStringGridStrings::Objects

TStringGridStrings	See also

Lists the objects associated with the strings listed by the Strings property.

__property System::TObject* Objects[int Index] = {read=GetObject, write=PutObject};

Description

Use Objects to obtain the object associated with a string in the Strings array. Set Objects to associate an object with one of the strings in the Strings array. Each entry in the Objects array points to the same object as the entry for the corresponding cell in the Objects property array of the string grid.


TStringGridStrings::Strings

TStringGridStrings	See also

Lists the strings displayed in the row or column of the string grid that is represented by the TStringGridStrings object.

__property System::AnsiString Strings[int Index] = {read=Get, write=Put};

Description

Use Strings to read or set the string for one of the cells in the row or column represented by the TStringGridStrings object. Each string appears in the corresponding cell of the string grid. To locate the object associated with the string, use the Objects property array.


TStringGridStrings methods

TStringGridStrings	Alphabetically

In TStringGridStrings

~TStringGridStrings

Assign

Delete

Insert

TStringGridStrings

Derived from TStrings

Add

AddObject

AddStrings

Append

BeginUpdate

Clear

EndUpdate

Equals

Exchange

GetText

IndexOf

IndexOfName

IndexOfObject

InsertObject

LoadFromFile

LoadFromStream

Move

SaveToFile

SaveToStream

SetText

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStringGridStrings methods

TStringGridStrings	By object

~TStringGridStrings

Add

AddObject

AddStrings

Append

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

EndUpdate

Equals

Exchange

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetText

IndexOf

IndexOfName

IndexOfObject

InheritsFrom

InitInstance

Insert

InsertObject

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

Move

NewInstance

SafeCallException

SaveToFile

SaveToStream

SetText

TStringGridStrings


TStringGridStrings::Assign

TStringGridStrings	See also

Copies the list of strings and objects from another TStrings object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Call Assign to copy the strings and objects from a source object of type TStrings. If the source object has more strings than the number of cells in the row or column represented by the TStringGridStrings object, Assign only copies the first Count strings and objects.

If the Source parameter is not a TStrings object, Assign calls the parent class’s method.


TStringGridStrings::TStringGridStrings

TStringGridStrings	See also

Creates an instance of TStringGridStrings.

__fastcall TStringGridStrings(TStringGrid* AGrid, int AIndex);

Description

Do not create instances of TStringGridStrings. String grids create TStringGridStrings objects for every row and column, to allow quick access of the strings and objects associated with the cells in the grid.

The AGrid parameter specifies the string grid that will use the TStringGridStrings object. The AIndex parameter specifies the index of the row or column associated with the TStringGridStrings object. If AIndex is greater than 0, the TStringGridStrings object represents the row indexed by AIndex. If AIndex is less than 0, the TStringGridStrings object represents the column indexed by the absolute value of AIndex.   If AIndex is 0, the TStringGridStrings object represents an empty row or column.


TStringGridStrings::Delete

TStringGridStrings	See also

Prevents strings from being deleted.

virtual void __fastcall Delete(int Index);

Description

Because TStringGridStrings objects represent the rows or columns of a string grid, the number of entries in the list must correspond exactly to the number of cells in the corresponding row or column. Rather than allow entries to be deleted, destroying this correspondence, Delete throws an EInvalidGridOperation exception.


TStringGridStrings::Insert

TStringGridStrings	See also

Prevents strings from being inserted.

virtual void __fastcall Insert(int Index, const System::AnsiString S);

Description

Because TStringGridStrings objects represent the rows or columns of a string grid, the number of entries in the list must correspond exactly to the number of cells in the corresponding row or column. Rather than allow entries to be inserted, destroying this correspondence, Insert throws an EInvalidGridOperation exception.


TStringGridStrings::~TStringGridStrings

TStringGridStrings

~TStringGridStrings frees the memory associated with the TStringGridStrings object.

__fastcall virtual ~TStringGridStrings(void) { }

Description

Do not call ~TStringGridStrings directly. Instead, use the delete keyword on the object, which causes ~TStringGridStrings to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TStrings


TStrings

Hierarchy	Properties	Methods	See also

TStrings is the base class for objects that represent a list of strings.

Unit

classes

Description

Derive a class from TStrings to store and manipulate a list of strings. TStrings contains pure virtual methods and should not be directly instantiated.

Descendants of TStrings can represent several individual strings, such as the individual lines that appear in a list box. Some objects use descendants of TStrings to represent one long body of text so that it can be manipulated in smaller chunks.

TStrings introduces many properties and methods to

•	Add or delete strings at specified positions in the list.

•	Rearrange the strings in the list.

•	Access the string at a particular location.

•	Read the strings from or write the strings to a file or stream.

•	Associate an object with each string in the list.


TStrings properties

TStrings	Alphabetically	Legend

In TStrings

Capacity

CommaText

Count

Names

Objects

Strings

StringsAdapter

Text

Values


TStrings properties

TStrings	By object	Legend

Capacity

CommaText

Count

Names

Objects

Strings

StringsAdapter

Text

Values


TStrings::Capacity

TStrings	See also

Indicates the number of strings the TStrings object can hold.

__property int Capacity = {read=GetCapacity, write=SetCapacity, nodefault};

Description

Read Capacity to determine the currently allocated size of the string list. For the TStrings object, reading Capacity returns the Count property, and setting Capacity does nothing. Descendants of TStrings can override this property to allow a string list to allocate memory for entries that have not been added to the list.


TStrings::CommaText

TStrings	See also

Lists the strings in the TStrings object in system data format (SDF).

__property System::AnsiString CommaText = {read=GetCommaText, write=SetCommaText};

Description

Use CommaText to get or set all the strings in the TStrings object in a single comma-delimited string.

When retrieving CommaText, any string in the list that include spaces, commas or quotes will be contained in double quotes, and any double quotes in a string will be repeated. For example, if the list contains the following strings:

Stri,ng 1

Stri"ng 2

String 3

String4

CommaText will return:

"Stri,ng 1","Stri""ng 2","String 3",String4

When assigning CommaText, the value is parsed as SDF formatted text. For SDF format, strings are separated by commas or spaces, and optionally enclosed in double quotes. Double quote marks that are part of the string are repeated to distinguish them from the quotes that surround the string. Spaces and commas that are not contained within double quote marks are delimiters. Two commas next to each other will indicate an empty string, but spaces that appear next to another delimiter are ignored. For example, suppose CommaText is set to:

"Stri,ng 1", "Stri""ng 2" , String 3,String4

The list will then contain:

Stri,ng 1

Stri"ng 2

String

3

String4


TStrings::Count

TStrings	See also 	Example

Introduces an abstract property to represent the number of strings in the list.

__property int Count = {read=GetCount, nodefault};

Description

Descendants of TStrings implement a Count property to indicate the number of strings in the list.

Use the Count property when iterating over all the strings in the list, or when trying to locate the position of a string relative to the last string in the list.


TStrings::Names

TStrings	See also 	Example

Indicates the name part of strings with the form Name=Value.

__property System::AnsiString Names[int Index] = {read=GetName};

Description

When the list of strings for the TStrings object includes strings of the form Name=Value, read Names to access the name part of a string. Names is the name part of the string at the position indicated by Index. Index gives the position of the string, where 0 is the first string, 1 is the second string, and so on. If the string at the specified position is not of the form Name=Value, Names returns an empty string.

Strings of the form Name=Value are commonly found in .INI files. For example, here are a few strings taken from a typical .INI file:

DisplayGrid=1

SnapToGrid=1

GridSizeX=8

GridSizeY=8

The strings that make up the Params property of a database component (TDatabase) have this format as well.

The Name that identifies the string is to the left of the equal sign (=), and the current Value of the Name identifier is on the right side. There should be no spaces present before or after the equal sign.


TStrings::Objects

TStrings	See also 	Example

Represents a set of objects that are associated one with each of the strings in the Strings property.

__property System::TObject* Objects[int Index] = {read=GetObject, write=PutObject};

Description

Setting the Objects property for TStrings does nothing. Reading the Objects property for TStrings returns NULL. Descendent classes can associate objects with the strings in the set by implementing the Objects property.

Use the Objects property of a descendent of TStrings to get or set the object associated with the string at the position indicated by Index. Index gives the position of the string associated with the object, where 0 is the first string, 1 is the second string, and so on. If a descendant of TStrings does not support the Objects property, reading this property returns NULL.


TStrings::Strings

TStrings	See also 	Example

References the strings in the list by their positions.

__property System::AnsiString Strings[int Index] = {read=Get, write=Put};

Description

Descendants of TStrings must implement an accessor function for the Strings property to return the string at the position indicated by Index. Index gives the position of the string, where 0 is the first string, 1 is the second string, and so on.

Use the Strings property to get or set the string at a particular position.


TStrings::StringsAdapter

TStrings	See also

Implements an IStrings interface that enables the TStrings object to communicate using OLE.

__property _di_IStringsAdapter StringsAdapter = {read=FAdapter, write=SetStringsAdapter};

Description

Do not use the StringsAdapter property. StringsAdapter is used internally by ActiveX controls to communicate information through an OLE interface.


TStrings::Text

TStrings	See also

Lists the strings in the TStrings object as a single string with the individual strings delimited by carriage returns and line feeds.

__property System::AnsiString Text = {read=GetTextStr, write=SetTextStr};

Description

Use Text to get or set all the strings in the TStrings object in a single string delimited by carriage return, line feed pairs.

When reading Text, the strings in the list will be separated by carriage return, line feed pairs. If any of the strings in the list contain a carriage return and line feed pair, the resulting value of Text will appear to contain more strings than is indicated by the Count property.

When setting Text, the value will be parsed by separating into substrings whenever a carriage return or linefeed is encountered. (The two do not need to form pairs).

If the strings in the list contain carriage return or linefeed characters, a less ambiguous format for the strings is available through the CommaText property.


TStrings::Values

TStrings	See also 	Example

Represents the value part of a string associated with a given Name, on strings with the form Name=Value.

__property System::AnsiString Values[System::AnsiString Name] = {read=GetValue, write=SetValue};

Description

When the list of strings for the TStrings object includes strings of the form Name=Value, use Values to get or set the value part of a string associated with a specific name part. If the list does not contain any strings of the proper Name=Value form, or if none of those strings matches the Name index, Values returns an empty string.

Strings of the form Name=Value are commonly found in .INI files. For example, here are a few strings taken from a typical .INI file:

DisplayGrid=1

SnapToGrid=1

GridSizeX=8

GridSizeY=8

The strings that make up the Params property of a database component (TDatabase) have this format as well.

The Name that identifies the string is to the left of the equal sign (=), and the current Value of the Name identifier is on the right side. There should be no spaces present before or after the equal sign.


TStrings methods

TStrings	Alphabetically

In TStrings

~TStrings

Add

AddObject

AddStrings

Append

Assign

BeginUpdate

Clear

Delete

EndUpdate

Equals

Exchange

GetText

IndexOf

IndexOfName

IndexOfObject

Insert

InsertObject

LoadFromFile

LoadFromStream

Move

SaveToFile

SaveToStream

SetText

TStrings

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStrings methods

TStrings	By object

~TStrings

Add

AddObject

AddStrings

Append

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

EndUpdate

Equals

Exchange

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetText

IndexOf

IndexOfName

IndexOfObject

InheritsFrom

InitInstance

Insert

InsertObject

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

Move

NewInstance

SafeCallException

SaveToFile

SaveToStream

SetText

TStrings


TStrings.Add
TStrings::Add

TStrings	See also	Example

Adds a string at the end of the list.

virtual int __fastcall Add(const System::AnsiString S);

Description

Call Add to add a string to the end of the list. Add returns the index of the new string.


TStrings::AddObject

TStrings	See also 	Example

Adds a string to the list, and associates an object with the string.

virtual int __fastcall AddObject(const System::AnsiString S, System::TObject* AObject);

Description

Call AddObject to add a string and its associated object to the list. AddObject returns the index of the new string and object.


TStrings::AddStrings

TStrings	See also	Example

Adds a group of strings to the list.

virtual void __fastcall AddStrings(TStrings* Strings);

Description

Call AddStrings to add the strings from another TStrings object to the list. If both the source and destination TStrings objects support objects associated with their strings, references to the associated objects will be added as well.


TStrings::Append

TStrings	See also 	Example

Adds the string S to the list.

void __fastcall Append(const System::AnsiString S);

Description

Append is the same as the Add method, except that it does not return a value. Use Append when there is no need to know the index of the string after it has been added, or with descendants of TStrings for which the index returned is not meaningful.

For example, the TStrings descendant used by memo objects uses an index to determine where to insert a string, but the inserted string does not necessarily end up as a single string in the list. Part of the inserted text may become part of the previous string, and part may be broken off into a subsequent string. The index returned by Add is not meaningful in this case.

Use Append rather than Add as a parameter for a function requiring a TGetStrProc.


TStrings::Assign

TStrings	See also	Example

Sets the strings in the list, and possibly associated objects, from a source object.

virtual void __fastcall Assign(TPersistent* Source);

Description

Use Assign to set the value of the TStrings object from another object. If Source is of type TStrings, the list is set to the list of the source TStrings object, and if associated objects are supported, any associated objects are copied from the Source as well.

If Source is not of type TStrings, the inherited Assign will set the value of the list from any object that supports TStrings in its AssignTo method.


TStrings::BeginUpdate

TStrings	See also 	Example

Enables the TStrings object to track when the list of strings is changing.

void __fastcall BeginUpdate(void);

Description

BeginUpdate is called automatically by any property or method that changes the list of strings. Once the changes are complete, the property or method calls EndUpdate. Call BeginUpdate before directly modifying the strings in the list, and EndUpdate after. When implementing properties or methods that change the list in descendants of TStrings, call BeginUpdate before the changes are made, and EndUpdate when the changes are complete.

TStrings simply keeps track of when the list of strings is being changed. Some descendants of TStrings use this information to perform certain actions, such as telling a control to repaint, when updates are complete.


TStrings::Clear

TStrings	See also 	Example

Introduces a pure virtual method to empty the list and any associated objects.

virtual void __fastcall Clear(void) = 0;

Description

Descendants of TStrings implement a Clear method to delete all the strings in the list, and to remove any references to associated objects.


TStrings::Delete

TStrings	See also	Example

Introduces a pure virtual method to delete a specified string from the list.

virtual void __fastcall Delete(int Index) = 0;

Description

Descendants of TStrings implement a Delete method to remove a specified string from the list. If an object is associated with the string, the reference to the object is removed as well. Index gives the position of the string, where 0 is the first string, 1 is the second string, and so on.


TStrings::~TStrings

TStrings	See also

Destroys an instance of TStrings.

__fastcall virtual ~TStrings(void);

Description

Do not call ~TStrings directly in an application. Instead, use the delete keyword.


TStrings::EndUpdate

TStrings	See also 	Example

Enables the TStrings object to keep track of when the list of strings has finished changing.

void __fastcall EndUpdate(void);

Description

EndUpdate is called automatically by any property or method that changes the list of strings. Call BeginUpdate before directly modifying the strings in the list, and EndUpdate after. When implementing properties or methods that change the list in descendants of TStrings, call BeginUpdate before the changes are made, and EndUpdate when the changes are complete.

TStrings simply keeps track of when the list of strings is being changed. Some descendants of TStrings use this information to perform certain actions, such as telling a control to repaint, when updates are complete.


TStrings::Equals

TStrings	See also

Compares the list of strings to the list from another TStrings object and returns true if the two lists are the same.

bool __fastcall Equals(TStrings* Strings);

Description

Call Equals to compare the lists in two TStrings objects. Equals compares only the strings, not any references to associated objects. Equals returns true if the lists for both TStrings objects have the same number of strings and the strings in each list are identical. Equals returns false if the lists are different in length, if they contain different strings, or if the order of the strings in the two lists differ.


TStrings::Exchange

TStrings	See also

Swaps the position of two strings in the list.

virtual void __fastcall Exchange(int Index1, int Index2);

Description

Call Exchange to rearrange the strings in the list. The strings are specified by their index values in the Index1 and Index2 parameters. Indexes are zero-based, so the first string in the list has an index value of 0, the second has an index value of 1, and so on.

If either string has an associated object, Exchange changes the position of the object as well.


TStrings::GetText

TStrings	See also

Allocates a text buffer and fills it with the value of the Text property.

virtual char * __fastcall GetText(void);

Description

Call GetText to obtain a dynamically allocated character buffer containing all of the strings in the list. Individual strings are separated by a carriage return and line feed. The caller is responsible for freeing the returned value.


TStrings::IndexOf

TStrings	See also 	Example

Returns the position of a string in the list.

virtual int __fastcall IndexOf(const System::AnsiString S);

Description

Call IndexOf to obtain the position of the first occurrence of the string S. IndexOf returns the 0-based index of the string. Thus, if S matches the first string in the list, IndexOf returns 0, if S is the second string, IndexOf returns 1, and so on. If the string is not in the string list, IndexOf returns -1.

Note:	If the string appears in the list more than once, IndexOf returns the position of the first occurrence.


TStrings::IndexOfName

TStrings	See also 	Example

Returns the position of the first string with the form Name=Value with the specified name part.

int __fastcall IndexOfName(const System::AnsiString Name);

Description

Call IndexOfName to locate the first occurrence of a string with the form Name=Value where the name part is equal to the Name parameter. IndexOfName returns the 0-based index of the string. If no string in the list has the indicated name, IndexOfName returns -1.

Strings of the form Name=Value are commonly found in .INI files. For example, here are a few strings taken from a typical .INI file:

DisplayGrid=1

SnapToGrid=1

GridSizeX=8

GridSizeY=8

The strings that make up the Params property of a database component (TDatabase) have this format as well.

The Name that identifies the string is to the left of the equal sign (=), and the current Value of the Name identifier is on the right side. There should be no spaces present before or after the equal sign.

Note:	If there is more than one string with a name portion matching the Name parameter, IndexOfName returns the position of the first such string.


TStrings::IndexOfObject

TStrings	See also	Example

Returns the index of the first string in the list associated with a given object.

int __fastcall IndexOfObject(System::TObject* AObject);

Description

Call IndexOfObject to locate the first string in the list associated with the object AObject. Specify the object you want to locate as the value of the AObject parameter. IndexOfObject returns the 0-based index of the string and object. If the object is not associated with any of the strings, IndexOfObject returns -1.


TStrings::Insert

TStrings	See alsoExample

Introduces a pure virtual method to insert a string at a specified position.

virtual void __fastcall Insert(int Index, const System::AnsiString S) = 0;

Description

Descendants of TStrings implement an Insert method to add the string S to the list at the position specified by Index. If Index is 0, the string is inserted at the beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.

All methods that add strings to the list use the Insert method to add the string.

If the string has an associated object, use the InsertObject method instead.


TStrings::InsertObject

TStrings	See also 	Example

Inserts a string into the list at the specified position, and associates it with an object.

void __fastcall InsertObject(int Index, const System::AnsiString S, System::TObject* AObject);

Description

Call InsertObject to insert the string S into the list at the position identified by Index, and associate it with the object AObject. If Index is 0, the string is inserted at the beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.


TStrings::LoadFromFile

TStrings	See also 	Example

Fills the list with the lines of text in a specified file.

virtual void __fastcall LoadFromFile(const System::AnsiString FileName);

Description

Call LoadFromFile to fill the list of the TStrings object from the file specified by FileName. Each line in the file, as indicated by carriage return or linefeed characters, is appended as a string in the list.


TStrings::LoadFromStream

TStrings	See also	Example

Fills the list with lines of text read from a stream.

virtual void __fastcall LoadFromStream(TStream* Stream);

Description

Call LoadFromStream to fill the list of the TStrings object from the stream specified by Stream. The text read from the stream is parsed into strings separated by carriage return or linefeed characters. Thus, LoadFromStream reads the value of the Text property.

If the stream is a file stream, LoadFromStream does the same thing as LoadFromFile, except the application must create and destroy the file stream.


TStrings::Move

TStrings	See also 	Example

Changes the position of a string in the list.

virtual void __fastcall Move(int CurIndex, int NewIndex);

Description

Use Move to move the string at position CurIndex so that it occupies the position NewIndex. The positions are specified as 0-based indexes. For example, the following line of code moves the string in the first position to the last position.

MyStringsObject->Move(0, MyStringsObject->Count - 1);

If the string has an associated object, the object remains associated with the string in its new position.


TStrings::SaveToFile

TStrings	See also 	Example

Saves the strings in the list to the specified file.

virtual void __fastcall SaveToFile(const System::AnsiString FileName);

Description

Call SaveToFile to save the strings in the list to the file specified by FileName. Each string in the list is written to a separate line in the file.


TStrings::SaveToStream

TStrings	See also	Example

Writes the value of the Text property to a stream object.

virtual void __fastcall SaveToStream(TStream* Stream);

Description

Call SaveToStream to save the strings in the list to the stream specified by the Stream parameter. SaveToStream writes the strings delimited by carriage return, line feed pairs. If the stream is a file stream, SaveToStream does the same thing as SaveToFile, except the application must create and destroy the file stream.


TStrings::SetText

TStrings	See also

Sets the Text property.

virtual void __fastcall SetText(char * Text);

Description

Call SetText to replace the list with the strings specified by the Text parameter. SetText adds strings one at a time to the list, using the carriage returns or linefeed characters in Text as delimiters indicating when to add a new string.


TStrings::TStrings

TStrings

TStrings creates a new TStrings object.

__fastcall TStrings(void) : Classes::TPersistent() { }

Description

Do not create instances of TStrings. TStrings methods rely on pure virtual methods that must be overridden in descendant objects.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TStringStream

Hierarchy	Properties	Methods	See also

TStringStream provides file-like access to information stored as a long string.

Unit

classes

Description

Use TStringStream to store data as a long string enhanced with I/O capabilities. TStringStream is useful as an intermediary object that can hold text as well as read it from or write it to another storage medium. TStringStream provides a mechanism for manipulating text that is obtained from a less accessible medium.


TStringStream properties

TStringStream	Alphabetically	Legend

In TStringStream

DataString

Derived from TStream

Position

Size


TStringStream properties

TStringStream	By object	Legend

DataString

Position

Size


TStringStream::DataString

TStringStream	See also

Provides direct access to the string that stores the text represented by the TStringStream object.

__property System::AnsiString DataString = {read=FDataString};

Description

Use DataString to get access to the text of the stream. The text represents the information that is being transferred by means of the string stream. Size is the number of bytes in the string, and Position is the current position within DataString.

Note:	DataString is a read-only property. DataString can be used to change the contents of the string, but applications can’t change the DataString itself.


TStringStream methods

TStringStream	Alphabetically

In TStringStream

~TStringStream

Read

ReadString

Seek

TStringStream

Write

WriteString

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStringStream methods

TStringStream	By object

~TStringStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

ReadString

SafeCallException

Seek

TStringStream

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

WriteString


TStringStream::TStringStream

TStringStream	See also

Creates an instance of TStringStream.

__fastcall TStringStream(const System::AnsiString AString);

Description

Call TStringStream indirectly, using the new keyword, to instantiate a TStringStream object. TStringStream initializes the DataString property to the AString parameter.


TStringStream::Read

TStringStream	See also

Reads up to Count bytes from the string stream into Buffer, and advances the current position of the stream by the number of bytes read.

virtual int __fastcall Read(void *Buffer, int Count);

Description

Use Read to read the contents of the string stream into a buffer, starting at the current position. If Count extends beyond the end of the DataString, Read will only transfer the characters up to the end of the DataString, and advances the current position accordingly. If the return value is less than Count, it means that the end of the string was read.

The ReadBuffer method and ReadComponent method call Read to do the actual reading.

Note:	Read treats Count as an upper bound. The ReadBuffer method, by contrast, throws an exception if Count bytes cannot be read.


TStringStream::ReadString

TStringStream	See also

Returns a string that consists of up to Count bytes from the current position in the string stream, and advances the current position of the stream by the number of bytes read.

System::AnsiString __fastcall ReadString(int Count);

Description

Use Read to read the contents of the string stream into a string, starting at the current position. If Count extends beyond the end of the DataString, the returned string will only contain the characters up to the end of DataString, and the current position is advanced accordingly.

Note:	ReadString does the same thing as Read, except that it returns a string rather than filling a buffer.


TStringStream::Seek

TStringStream	See also

Moves the current position in the stream by Offset bytes, relative to a specified origin.

virtual int __fastcall Seek(int Offset, Word Origin);

Description

Use Seek to move the current position within the string stream by the indicated offset. Seek allows an application to read from or write to a particular location within the DataString.

If Offset is a negative number, the seek is backwards from the specified origin. The following table shows the different values of Origin and their meanings for seeking.

Value	Meaning

soFromBeginning	Offset is from the beginning of DataString. Seek moves to the position Offset. Offset must be >= 0.

soFromCurrent	Offset is from the current position. Seek moves to Position + Offset.

soFromEnd	Offset is from the end of Memory. Offset must be <= 0 to indicate a number of bytes before the end of the DataString.

Seek returns the new value of the Position property.


TStringStream::Write

TStringStream	See also

Write writes Count bytes from Buffer to the current position in the string stream and updates the current position by Count bytes.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Use Write to replace the end of the string from the current position on with the first Count bytes of Buffer. Write will change the Size property to reflect the new length of the DataString.

Write always writes Count bytes from Buffer, even if a null character is included as one of the Count bytes. Thus, Write is equivalent to the WriteBuffer method.


TStringStream::WriteString

TStringStream	See also

Concatenates a specified string to the current position in the string stream, and updates the current position accordingly.

void __fastcall WriteString(const System::AnsiString AString);

Description

Use WriteString to replace the end of the string from the current position on with the string specified by the AString parameter. WriteString changes the Size property to reflect the new length of the DataString.


TStringStream::~TStringStream

TStringStream

~TStringStream frees the memory associated with the TStringStream object.

__fastcall virtual ~TStringStream(void) { }

Description

Do not call ~TStringStream directly. Instead, use the delete keyword on the object, which causes ~TStringStream to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TStream


TStringField

Hierarchy	Properties	Methods	Events	See also

TStringField represents a string field in a dataset.

Unit

db

Description

A value of a string field is physically stored as a sequence of up to 8192 characters. Common uses for string fields are to store text, such as names and addresses.

TStringField introduces properties to translate between string values and other data types, and to manage language driver conversions. As a descendent of TField, TStringField inherits many properties, methods, and events that are useful for managing the value and properties of a field in a database.


TStringField properties

TStringField	Alphabetically	Legend

In TStringField

AsBoolean

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

DataSize

Transliterate

Value

Derived from TField

Alignment

AsCurrency

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TStringField properties

TStringField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

Transliterate

ValidChars

Value

VCLComObject

Visible


TStringField::AsBoolean

TStringField	See also

Represents the value of the field as a Boolean value.

__property bool AsBoolean = {read=GetAsBoolean, write=SetAsBoolean, nodefault};

Description

Use AsBoolean to

•	Assign the string field value to a Boolean variable.

•	Assign a Boolean value to the string field.

AsBoolean returns true on reading the value of the field if its text begins with the letters Y, y, T or t (for Yes or True), and false otherwise. Using AsBoolean to write a TStringField's value sets the string to T or F.


TStringField::AsDateTime

TStringField	See also

Represents the value of the field as a TDateTime value.

__property System::TDateTime AsDateTime = {read=GetAsDateTime, write=SetAsDateTime};

Description

Use AsDateTime to

•	Assign the string field value to a TDateTime value.

•	Assign a TDateTime value to the string field.

Reading AsDateTime converts the value of the field to a date-time using the StrToDateTime function. Setting AsDateTime converts the date-time value to a string using the DateTimeToStr function.


TStringField::AsFloat

TStringField	See also

Represents the value of the field as a floating-point value.

__property double AsFloat = {read=GetAsFloat, write=SetAsFloat};

Description

Use AsFloat to

•	Assign the string field value to a floating-point value.

•	Assign a floating-point value to the string field.

For example, this code assigns a floating-point value to a string field value:

MyStringField->AsFloat = 7.345;

To assign a string field value to a floating-point value, use code similar to this:

FloatVariable = MyStringField->AsFloat;

Reading AsFloat converts the value of the field to a floating-point value using the StrToFloat function. Setting AsFloat converts the floating-point value to a string using the FloatToStr function.


TStringField::AsInteger

TStringField	See also

Represents the value of the field as an integer value.

__property int AsInteger = {read=GetAsInteger, write=SetAsInteger, nodefault};

Description

Use AsInteger to

•	Assign the string field value to an integer value.

•	Assign an integer value to the string field.

For example, this code assigns integer value to a string field value:

MyStringField->AsInteger = 12;

To assign a string field value to an integer value, use code similar to this:

IntegerVariable = MyStringField->AsInteger;

Reading AsInteger converts the value of the field to an integer using the StrToInt function. Setting AsInteger converts the integer to a string using the IntToStr function.


TStringField::AsString

TStringField	See also 	Example

Represents the value of the field.

__property System::AnsiString AsString = {read=GetAsString, write=SetAsString};

Description

String values need no conversion, because the native format of a string field is a string. For string fields, AsString is the same as the Value property. AsString provides a uniform interface that allows applications to get or set string values with generic field components when the internal format of the data is not known.

When setting the AsString property, TStringField converts the assigned string from ANSI, using the language driver for the dataset, if the Transliterate property is true. Strings that have more characters than permitted by the value of the Size property are truncated when setting AsString.


TStringField::AsVariant

TStringField	See also

Represents the value of a string field as a variant value.

__property System::Variant AsVariant = {read=GetAsVariant, write=SetAsVariant};

Description

Use AsVariant to

•	Assign the string field value to variant variable.

•	Assign a variant value to the string field.

Using variants is useful when both the field type and the type of the value to be assigned to the field are unknown.


TStringField::DataSize

TStringField	See also 	Example

Indicates amount of memory needed to store the string field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a string field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For string fields, DataSize is one more than the value of the Size property. The characters in the string can take up to Size bytes, and the extra byte is the null character at the end.


TStringField::Transliterate

TStringField	See also

Indicates whether to convert the value of the string field between the ANSI character set and the character set identified by the dataset when reading from or writing to the physical database tables.

__property bool Transliterate = {read=FTransliterate, write=FTransliterate, default=1};

Description

Use Transliterate when the physical database table identified by the dataset does not use an ANSI language driver and the data may contain extended ASCII characters.

When Transliterate is true, the AnsiToNative function is called to translate the ANSI characters to the character set used by the dataset when the string field value is set. When the string field value is read, the NativeToAnsi function is called to translate the characters in the database table to the ANSI character set.


TStringField::Value

TStringField	See also

Represents the data in the string field.

__property System::AnsiString Value = {read=GetAsString, write=SetAsString};

Description

Use Value to read data directly from and write data directly to a string field component at runtime. Using the Value property is the same as using the AsString property. Use Value when you know the field component is a string field. Use AsString when working with a generic field component.

When setting the Value property, TStringField converts the assigned string from ANSI, using the language driver for the dataset, if the Transliterate property is true. Strings that have more characters than permitted by the value of the Size property are truncated when setting Value.


TStringField events

TStringField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TStringField events

TStringField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TStringField methods

TStringField	Alphabetically

In TStringField

~TStringField

TStringField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TStringField methods

TStringField	By object

~TStringField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TStringField

Validate


TStringField::TStringField

TStringField	See also

Creates an instance of a TStringField object.

__fastcall virtual TStringField(Classes::TComponent* AOwner);

Description

It is seldom necessary to call TStringField directly, because a string field component is instantiated automatically for all string fields in a dataset. To create a TStringField object, use the new keyword.

After calling the parent object’s constructor, TStringField sets

•	DataType to ftString.

•	Size to 20.

•	Transliterate to true.


TStringField::~TStringField

TStringField

~TStringField frees the memory associated with the TStringField object.

__fastcall virtual ~TStringField(void) { }

Description

Do not call ~TStringField directly. Instead, use the delete keyword on the object, which causes ~TStringField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField


 TStringGrid

Hierarchy	Properties	Methods	Events	See also

TStringGrid is a grid control designed to simplify the handling of strings and associated objects.

Unit

grids

Description

Add a TStringGrid object to a form to present textual data in a tabular format. TStringGrid provides many properties to control the appearance of the grid, as well as events and methods that take advantage of the tabular organization of the grid in responding to user actions.

TStringGrid introduces the ability to associate an object with each string in the grid. These objects can encapsulate any information or behavior represented by the strings that are presented to the user.

If the strings to be presented in a grid represent field values from the records in a dataset, use TDBGrid instead.


TStringGrid properties

TStringGrid	Alphabetically	Legend

In TStringGrid

Cells

Cols

Objects

Rows

Derived from TCustomGrid

BorderStyle

Col

ColCount

ColWidths

DefaultColWidth

DefaultDrawing

DefaultRowHeight

EditorMode

FixedColor

FixedCols

FixedRows

GridHeight

GridLineWidth

GridWidth

LeftCol

Options

Row

RowCount

RowHeights

ScrollBars

Selection

TabStops

TopRow

VisibleColCount

VisibleRowCount

Derived from TCustomControl

Canvas

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TStringGrid properties

TStringGrid	By object	Legend

Align

BorderStyle

BoundsRect

Brush

Canvas

Cells

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Col

ColCount

Color

Cols

ColWidths

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DefaultColWidth

DefaultDrawing

DefaultRowHeight

DesignInfo

DragCursor

DragMode

EditorMode

Enabled

FixedColor

FixedCols

FixedRows

Font

GridHeight

GridLineWidth

GridWidth

Handle

Height

HelpContext

Hint

Left

LeftCol

Name

Objects

Options

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

Row

RowCount

RowHeights

Rows

ScrollBars

Selection

ShowHint

Showing

TabOrder

TabStop

TabStops

Tag

Top

TopRow

VCLComObject

Visible

VisibleColCount

VisibleRowCount

Width

WindowProc


TStringGrid::Cells

TStringGrid	See also 	Example

Lists the strings for each cell in the grid.

__property System::AnsiString Cells[int ACol][int ARow] = {read=GetCells, write=SetCells};

Description

Use Cells to access the string within a particular cell. ACol is the column coordinate of the cell, and ARow is the row coordinate of the cell. The first row is row zero, and the first column is column zero.

The ColCount and RowCount property values define the size of the array of strings.

To access the objects associated with the strings in the Cells array, use the Objects property.


TStringGrid::Cols

TStringGrid	See also

Lists strings with their associated objects for each column.

__property Classes::TStrings* Cols[int Index] = {read=GetCols, write=SetCols};

Description

Use Cols to access all the strings for a single column, along with their associated objects. The number of strings and associated objects is always equal to the value of the ColCount property, the number of columns in the grid. The Index parameter is the number of the column, where the value of the first column in the grid is zero.

To get all the strings and objects for a row, rather than for a column, use the Rows property.


TStringGrid::Objects

TStringGrid	See also

Lists the objects for each cell in the grid.

__property System::TObject* Objects[int ACol][int ARow] = {read=GetObjects, write=SetObjects};

Description

Use the Objects property to access the object associated with a particular cell. The ColCount and RowCount values define the size of the array of objects. ACol is the column coordinate of the cell, and ARow is the row coordinate of the cell, where the first column is column 0, and the first row is row 0.

Note:	The string grid does not own the objects in the Objects array. Objects added to the Objects array still exist even if the string grid is destroyed. They must be explicitly destroyed by the application.


TStringGrid::Rows

TStringGrid	See also 	Example

Lists the strings and their associated objects for each row.

__property Classes::TStrings* Rows[int Index] = {read=GetRows, write=SetRows};

Description

Use Rows to access all the strings for a single row, along with their associated objects. The number of strings and associated objects is always equal to the value of the RowCount property, the number of rows in the grid. The Index parameter is the number of the row, where the value of the first row in the grid is zero.

To get all the strings and objects for a column, rather than for a row, use the Cols property.


TStringGrid events

TStringGrid	Alphabetically	Legend

Derived from TDrawGrid

OnColumnMoved

OnDrawCell

OnGetEditMask

OnGetEditText

OnRowMoved

OnSelectCell

OnSetEditText

OnTopLeftChanged

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TStringGrid events

TStringGrid	By object	Legend

OnClick

OnColumnMoved

OnDblClick

OnDragDrop

OnDragOver

OnDrawCell

OnEndDrag

OnEnter

OnExit

OnGetEditMask

OnGetEditText

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnRowMoved

OnSelectCell

OnSetEditText

OnStartDrag

OnTopLeftChanged


TStringGrid methods

TStringGrid	Alphabetically

In TStringGrid

~TStringGrid

TStringGrid

Derived from TDrawGrid

CellRect

MouseToCell

Derived from TCustomGrid

MouseCoord

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TStringGrid methods

TStringGrid	By object

~TStringGrid

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

CellRect

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

MouseCoord

MouseToCell

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TStringGrid

Update

UpdateControlState


TStringGrid::TStringGrid

TStringGrid	See also

Creates an instance of TStringGrid.

__fastcall virtual TStringGrid(Classes::TComponent* AOwner);

Description

Call TStringGrid indirectly, using the new keyword, to create an instance of TStringGrid at runtime. For string grids placed on forms at design time, TStringGrid is called automatically.

Pass a single Component as a parameter to provide the string grid with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the string grid in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.

After calling the parent object’s constructor, TStringGrid creates the helper objects used by TStringGrid to manage the array of strings and their associated objects.


TStringGrid::~TStringGrid

TStringGrid	See also

Destroys an instance of TStringGrid.

__fastcall virtual ~TStringGrid(void);

Description

Do not call ~TStringGrid directly in an application. Instead, use the delete keyword.

~TStringGrid frees the helper objects used to manage the array of strings and their associated objects.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TCustomGrid

TDrawGrid


TStringList

Hierarchy	Properties	Methods	Events	See also

TStringList maintains a list of strings.

Unit

classes

Description

Use a string list object to store and manipulate a list of strings. TStringList implements the abstract properties and methods introduced by TStrings, and introduces new properties, events, and methods to

•	Sort the strings in the list.

•	Prohibit duplicate strings in sorted lists.

•	Respond to changes in the contents of the list.


TStringList properties

TStringList	Alphabetically	Legend

In TStringList

Capacity

Count

Duplicates

Objects

Sorted

Strings

Derived from TStrings

CommaText

Names

StringsAdapter

Text

Values


TStringList properties

TStringList	By object	Legend

Capacity

CommaText

Count

Duplicates

Names

Objects

Sorted

Strings

StringsAdapter

Text

Values


TStringList::Capacity

TStringList	See also

Indicates the number of strings the string list has allocated memory to hold.

__property int Capacity = {read=FCapacity, write=SetCapacity, nodefault};

Description

Use Capacity to find out how much memory is available for holding strings, or to reallocate the memory to allow more or fewer strings.

Capacity is the number of entries in the string list that have been allocated, as opposed to Count, which is the number of strings in the list. Thus, Capacity is always greater than or equal to Count.

Adding new strings will cause the Capacity property to increase if necessary, but setting the Capacity property will not change the Count property. Do not set Capacity to a value less than Count, or the list will be truncated and Count will indicate that the list contains more strings than is the case. Also, if Capacity is set to a value less than Count, the memory used to store the strings that are dropped from the list (as opposed to the entries in the list that point to those strings) is not freed.


TStringList::Count

TStringList	See also 	Example

Indicates the number of strings in the list.

__property int Count = {read=GetCount, nodefault};

Description

Use Count when iterating over all the strings in the list, or when trying to locate the position of a string relative to the last string in the list.


TStringList::Duplicates

TStringList	See also

Specifies whether duplicate strings can be added to sorted lists.

enum TDuplicates { dupIgnore, dupAccept, dupError };

__property TDuplicates Duplicates = {read=FDuplicates, write=FDuplicates, nodefault};

Description

Set Duplicates to specify what should happen when an attempt is made to add a duplicate string to a sorted list. The value of Duplicates should be one of the following.

Value	Meaning

dupIgnore	Ignore attempts to add duplicate strings to the sorted list.

dupError	Raise an EListError exception when an attempt is made to add duplicate strings to the sorted list.

dupAccept	Permit duplicate strings in the sorted list.

Set Duplicates before adding any strings to the list. Setting Duplicates to dupIgnore or dupError does nothing about duplicate strings that are already in the list.

Note:	Duplicates does nothing if the list is not sorted.


TStringList::Objects

TStringList	See also

Lists a set of objects associated one with each of the strings in the Strings property.

__property System::TObject* Objects[int Index] = {read=GetObject, write=PutObject};

Description

Associate an object with an existing string by setting the Objects property using the same index as that of the string in the Strings property. Look up the object associated with a string by reading the Objects property with the index of the string. Index gives the position of the string associated with the object, where 0 is the first string, 1 is the second string, and so on. Use the IndexOf method to find the index of the string.

For example, use Objects to associate bitmap objects with the strings in the string list. The Objects property then enables the application to quickly locate the bitmaps for display beside the strings in a listbox, or for drawing when the associated string is selected in a control.


TStringList::Sorted

TStringList	See also 	Example

Specifies whether the strings in the list should be automatically sorted.

__property bool Sorted = {read=FSorted, write=SetSorted, nodefault};

Description

Set Sorted to true to cause the strings in the list to be automatically sorted in ascending order. Set Sorted to false to allow strings to remain where they are inserted. When Sorted is false, the strings in the list can be put in ascending order at any time by calling the Sort method.

When Sorted is true, do not use Insert to add strings to the list. Instead, use Add, which will insert the new strings in the appropriate position. When Sorted is false, use Insert to add strings to an arbitrary position in the list, or Add to add strings to the end of the list.


TStringList::Strings

TStringList	See also

Lists the strings, referenced by a 0-based index.

__property System::AnsiString Strings[int Index] = {read=Get, write=Put};

Description

Use Strings to read or modify the string at a particular position. Index gives the position of the string, where 0 is the position of the first string, 1 is the position of the second string, and so on. To locate a particular string in the list, call the IndexOf method.


TStringList events

TStringList	Alphabetically

In TStringList

OnChange

OnChanging


TStringList events

TStringList	By object

OnChange

OnChanging


TStringList::OnChange

TStringList	See also

Occurs immediately after the list of strings changes.

__property TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to respond to changes in the list of strings. For example, if the string list is associated with a control, the OnChange event handler could tell the control to repaint itself whenever the content of the list changes.

Whenever strings in the list are added, deleted, moved, or modified, the following events take place:

1	First, an OnChanging event occurs before the change.

2	The strings are added, deleted, moved, or modified.

3	Finally, an OnChange event occurs.


TStringList::OnChanging

TStringList	See also

Occurs immediately before the list of strings changes.

__property TNotifyEvent OnChanging = {read=FOnChanging, write=FOnChanging};

Description

Write an OnChanging event handler to prepare for changes in the list of strings. For example, if the string list is associated with a control, the OnChanging event handler could tell the control to disable repaints until the OnChange event when the list has finished changing.

Whenever strings in the list are added, deleted, moved, or modified, the following events take place:

1	First, an OnChanging event occurs.

2	The strings are added, deleted, moved, or modified.

3	Finally, an OnChange event occurs after the changes are complete.


TStringList methods

TStringList	Alphabetically

In TStringList

~TStringList

Add

Clear

Delete

Exchange

Find

IndexOf

Insert

Sort

TStringList

Derived from TStrings

AddObject

AddStrings

Append

Assign

BeginUpdate

EndUpdate

Equals

GetText

IndexOfName

IndexOfObject

InsertObject

LoadFromFile

LoadFromStream

Move

SaveToFile

SaveToStream

SetText

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStringList methods

TStringList	By object

~TStringList

Add

AddObject

AddStrings

Append

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

EndUpdate

Equals

Exchange

FieldAddress

Find

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetText

IndexOf

IndexOfName

IndexOfObject

InheritsFrom

InitInstance

Insert

InsertObject

InstanceSize

LoadFromFile

LoadFromStream

MethodAddress

MethodName

Move

NewInstance

SafeCallException

SaveToFile

SaveToStream

SetText

Sort

TStringList


TStringList.Add
TStringList::Add

TStringList	See also	Example

Adds a new string to the list.

virtual int __fastcall Add(const System::AnsiString S);

Description

Call Add to add the string S to the list. If the list is sorted, S is added to the appropriate position in the sort order. If the list is not sorted, S is added to the end of the list. Add returns the position of the item in the list, where the first item in the list has a value of 0.

Note:	For sorted lists, Add will throw an EListError exception if the string S already appears in the list and Duplicates is set to dupError. If Duplicates is set to dupIgnore, trying to add a duplicate string to a sorted list does nothing.


TStringList::Clear

TStringList	See also

Deletes all the strings from the list.

virtual void __fastcall Clear(void);

Description

Call clear to empty the list of strings. All references to associated objects are also removed.


TStringList::Delete

TStringList	See also	Example

Removes the string specified by the Index parameter.

virtual void __fastcall Delete(int Index);

Description

Call Delete to remove a single string from the list. If an object is associated with the string, the reference to the object is removed as well. Index gives the position of the string, where 0 is the first string, 1 is the second string, and so on.


TStringList::~TStringList

TStringList	See also

Destroys an instance of TStringList.

__fastcall virtual ~TStringList(void);

Description

Do not call ~TStringList directly in an application. Instead, use the delete keyword.

~TStringList frees the memory allocated to hold the list of strings and object references before calling the parent object’s destructor.


TStringList::Exchange

TStringList	See also	Example

Swaps the position of two strings in the list.

virtual void __fastcall Exchange(int Index1, int Index2);

Description

Call Exchange to rearrange the strings in the list. The strings are specified by their index values in the Index1 and Index2 parameters. Indexes are zero-based, so the first string in the list has an index value of 0, the second has an index value of 1, and so on.

If either string has an associated object, Exchange changes the index of the object as well.

Caution:	Do not call Exchange on a sorted list except to swap two identical strings with different associated objects. Exchange does not check whether the list is sorted, and can destroy the sort order of a sorted list.


TStringList::Find

TStringList	See also 	Example

Locates the index for a string in a sorted list and indicates whether a string with that value already exists in the list.

virtual bool __fastcall Find(const System::AnsiString S, int &Index);

Description

Use Find to obtain the index in a sorted list where the string S should be added. If the string S already exists in the list, Find returns true. If the list does not contain S, Find returns false. The index where S should go is returned in the Index parameter. The value of Index is zero-based, where the first string has the index 0, the second string has the index 1, and so on.

Note:	Only use Find with sorted lists. For unsorted lists, use the IndexOf method instead.


TStringList::IndexOf

TStringList	See also	Example

Returns the position of a string in the list.

virtual int __fastcall IndexOf(const System::AnsiString S);

Description

Call IndexOf to obtain the position of the first occurrence of the string S. IndexOf returns the 0-based index of the string. Thus, if S matches the first string in the list, IndexOf returns 0, if S is the second string, IndexOf returns 1, and so on. If the string is not in the string list, IndexOf returns -1.


TStringList::Insert

TStringList	See also	Example

Inserts a string to the list at the position specified by Index.

virtual void __fastcall Insert(int Index, const System::AnsiString S);

Description

Call Insert to add the string S to the list at the position specified by Index. If Index is 0, the string is inserted at the beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.

If the string has an associated object, use the InsertObject method instead.

Note:	If the list is sorted, calling Insert or InsertObject will throw an EListError exception. Use Add or AddObject with sorted lists.


TStringList::Sort

TStringList	See also	Example

Sorts the strings in the list in ascending order.

virtual void __fastcall Sort(void);

Description

Call Sort to sort the strings in a list that has the Sorted property set to false. String lists with the Sorted property set to true are automatically sorted.


TStringList::TStringList

TStringList

Creates a new TStringList object.

__fastcall virtual ~TStringList(void);

Description

When creating a TStringList object, use the new keyword before the constructor to obtain an indirect reference to the string list.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TStrings


TStatusPanel

Hierarchy	Properties	Methods	See also

TStatusPanel represents a single panel of a status bar.

Unit

comctrls

Description

Each TStatusBar uses a TStatusPanels to maintain a collection of TStatusPanel objects.


TStatusPanel properties

TStatusPanel	Alphabetically	Legend

In TStatusPanel

Alignment

Bevel

DisplayName

Style

Text

Width

Derived from TCollectionItem

Collection

ID

Index


TStatusPanel properties

TStatusPanel	By object	Legend

Alignment

Bevel

Collection

DisplayName

ID

Index

Style

Text

Width


TStatusPanel::Alignment

TStatusPanel	See also

Specifies how text is aligned within the status panel.

enum TAlignment { taLeftJustify, taRightJustify, taCenter };

__property Classes::TAlignment Alignment = {read=FAlignment, write=SetAlignment, default=0};

Description

These are the possible values of Alignment:

Value	Meaning

taLeftJustify	Align text on the left side of the panel.

taCenter	Center the text in the panel.

taRightJustify	Align text on the right side of the panel.

Note:	If the status bar has a sizing grip, setting the Alignment of the last status panel to taRightJustify truncates the panel’s text.


TStatusPanel::Bevel

TStatusPanel

Determines the style of the panel’s border.

enum TStatusPanelBevel { pbNone, pbLowered, pbRaised };

__property TStatusPanelBevel Bevel = {read=FBevel, write=SetBevel, default=1};

Description

These are the possible values of Bevel:

Value	Meaning

pbNone	The panel has no bevel and appears flat.

pbLowered	The panel appears recessed.

pbRaised	The panel appears raised.


TListColumn::DisplayName
TStatusPanel::DisplayName

TStatusPanel	See also

DisplayName is a string that names an individual panel within a collection of panels.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

Use DisplayName to specify the name of the panel as it should appear in the Panels editor at design time. If the Text property is set, the value of DisplayName is the same as Text. Otherwise, DisplayName is the name of the list column class.


TStatusPanel::Style

TStatusPanel	See also

Determines how the status panel’s text is displayed.

enum TStatusPanelStyle { psText, psOwnerDraw };

__property TStatusPanelStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

If Style is set to psText (the default), the string contained in the Text property is displayed in the status panel, using the alignment specified by Alignment. The font is determined by the status bar’s Font property.

If Style is set to psOwnerDraw, the content displayed in the status panel is drawn at runtime on the status bar’s canvas by code in a TStatusBar::OnDrawPanel event handler.


TStatusPanel::Text

TStatusPanel 	Example

Specifies the text appearing in the status panel.

__property System::AnsiString Text = {read=FText, write=SetText};

Description

The Text property contains a string that appears in the status panel if Style is set to psText.


TStatusPanel::Width

TStatusPanel

Specifies the width of the status panel.

__property int Width = {read=FWidth, write=SetWidth, nodefault};

Description

The Width property determines the horizontal size of the status panel, in pixels.


TStatusPanel methods

TStatusPanel	Alphabetically

In TStatusPanel

~TStatusPanel

Assign

TStatusPanel

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStatusPanel methods

TStatusPanel	By object

~TStatusPanel

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TStatusPanel


TStatusPanel::Assign

TStatusPanel	See also

Copies the contents of the source status panel to a new status panel.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Assign copies the values of Alignment, Bevel, Style, Text, and Width from the source status panel.


TStatusPanel::TStatusPanel

TStatusPanel	See also

Creates and initializes a status panel.

__fastcall virtual TStatusPanel(Classes::TCollection* Collection);

Description

Do not call TStatusPanel directly. Instead, use the keyword new, which returns an indirect reference to the new status panel.

TStatusPanel takes a TStatusPanels instance as its argument.


TStatusPanel::~TStatusPanel

TStatusPanel

~TStatusPanel frees the memory associated with the TStatusPanel object.

__fastcall virtual ~TStatusPanel(void) { }

Description

Do not call ~TStatusPanel directly. Instead, use the delete keyword on the object, which causes ~TStatusPanel to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


TStatusPanels

Hierarchy	Properties	Methods	See also

TStatusPanels is a container for TStatusPanel objects.

Unit

comctrls

Description

Each TStatusPanels holds a collection of TStatusPanel objects in a TStatusBar. TStatusPanels maintains an index of the status panels in its Items array. The Count property contains the number of status panels in the collection. At design time, use the status bar’s Panels editor to add, remove, or modify status panels.


TStatusPanels properties

TStatusPanels	Alphabetically	Legend

In TStatusPanels

Items

Derived from TCollection

Count

ItemClass


TStatusPanels properties

TStatusPanels	By object	Legend

Count

ItemClass

Items


TStatusPanels::Items

TStatusPanels	See also	Example

Lists the status panels in the collection.

__property TStatusPanel* Items[int Index] = {read=GetItem, write=SetItem};

Description

The value of the Index parameter corresponds to the Index property of TStatusPanel. It represents the position of the status panel in the status bar.


TStatusPanels methods

TStatusPanels	Alphabetically

In TStatusPanels

~TStatusPanels

Add

TStatusPanels

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TStatusPanels methods

TStatusPanels	By object

~TStatusPanels

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TStatusPanels


TStatusPanels.Add

TStatusPanels	See also 	Example

Creates a new TStatusPanel instance and adds it to the Items array.

HIDESBASE TStatusPanel* __fastcall Add(void);

Description

Add returns the new status panel. At design time, use the Panels editor to add panels to the status bar.


TStatusPanels::TStatusPanels

TStatusPanels	See also

Creates and initializes a TStatusPanels object.

__fastcall TStatusPanels(TStatusBar* StatusBar);

Description

Do not call TStatusPanels directly. Instances of TStatusBar create the TStatusPanels object from their own constructors. If it is necessary to create a TStatusPanels object explicitly, use the keyword new, which returns an indirect reference to the new object.

The TStatusPanels method takes a TStatusBar instance as a parameter.


TStatusPanels::~TStatusPanels

TStatusPanels

~TStatusPanels frees the memory associated with the TStatusPanels object.

__fastcall virtual ~TStatusPanels(void) { }

Description

Do not call ~TStatusPanels directly. Instead, use the delete keyword on the object, which causes ~TStatusPanels to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


 TStatusBar

Hierarchy	Properties	Methods	Events	See also

TStatusBar represents a Windows status bar.

Unit

comctrls

Description

The TStatusBar component is a row of panels, usually aligned at the bottom of the form, that display information about the application as it runs. Each panel is represented by a TStatusPanel object listed in the Panels property. The SimplePanel property can be used to toggle the status bar at runtime between a single-panel and multiple-panel display.


TStatusBar properties

TStatusBar	Alphabetically	Legend

In TStatusBar

Canvas

Panels

SimplePanel

SimpleText

SizeGrip

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TStatusBar properties

TStatusBar	By object	Legend

Align

BoundsRect

Brush

Canvas

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

Panels

Parent

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

SimplePanel

SimpleText

SizeGrip

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TStatusBar::Canvas

TStatusBar	See also 	Example

Provides runtime access to the status bar’s drawing surface.

__property Graphics::TCanvas* Canvas = {read=FCanvas};

Description

The read-only Canvas property provides access to the status bar’s drawing surface that you can use when implementing a handler for the OnDrawPanel event.


TStatusBar::Panels

TStatusBar	See also 	Example

Lists the panels (TStatusPanel) in the status bar.

__property TStatusPanels* Panels = {read=FPanels, write=SetPanels};

Description

The Panels property holds a TStatusPanels—that is, a collection of TStatusPanel objects. At design time, you can add, remove, or modify panels with the Panels editor. To open the Panels editor, select the Panels property in the Object Inspector, then double-click in the Value column to the right or click the ellipsis (...) button.


TStatusBar::SimplePanel

TStatusBar	See also	Example

Determines whether the status bar displays a single panel or multiple panels.

__property bool SimplePanel = {read=FSimplePanel, write=SetSimplePanel, nodefault};

Description

If SimplePanel is set to true, the status bar consists of a single panel displaying the text in SimpleText. If SimplePanel is set to false, the status bar displays a separate panel for each item in its Panels property. To alter the appearance of the status bar at runtime, change the value of SimplePanel programmatically.


TStatusBar::SimpleText

TStatusBar	See also	Example

Contains the string that is displayed in the status bar when SimplePanel is set to true.

__property System::AnsiString SimpleText = {read=FSimpleText, write=SetSimpleText};

Description

SimpleText contains a text string to be displayed in the status panel when SimplePanel is true.


TStatusBar::SizeGrip

TStatusBar	See also

Determines whether the status bar is resizable at runtime.

__property bool SizeGrip = {read=FSizeGrip, write=SetSizeGrip, default=1};

Description

If SizeGrip is set to true, the status bar has a triangular grip on the lower right corner. The user can resize the status bar by dragging the grip with the mouse.

Note:	If Align is set to alBottom, alRight, or alClient, the sizing grip will not work. If the Alignment property of the last panel in the status bar is set to taRightJustify, the sizing grip will truncate the panel’s text.


TStatusBar events

TStatusBar	Alphabetically	Legend

In TStatusBar

OnDrawPanel

OnResize

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TStatusBar events

TStatusBar	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnDrawPanel

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnStartDrag


TStatusBar::OnDrawPanel

TStatusBar	See also 	Example

Occurs when a status panel needs to be redrawn.

typedef void __fastcall (__closure *TDrawPanelEvent)(TStatusBar* StatusBar, StatusPanel* Panel, const Windows::TRect &Rect);

__property TDrawPanelEvent OnDrawPanel = {read=FOnDrawPanel, write=FOnDrawPanel};

Description

The OnDrawPanel event occurs when a status panel needs to be redisplayed—for example, when the user resizes the status bar. The Rect parameter gives the (new) dimensions of the status panel. OnDrawPanel occurs only if the status panel’s Style property is set to psOwnerDraw.

TDrawPanelEvent is the type of the OnDrawPanel property.


TStatusBar::OnResize

TStatusBar

Occurs when the status panel is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

The OnResize event occurs whenever the entire status bar is resized at runtime.


TStatusBar methods

TStatusBar	Alphabetically

In TStatusBar

~TStatusBar

TStatusBar

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TStatusBar methods

TStatusBar	By object

~TStatusBar

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TStatusBar

Update

UpdateControlState


TStatusBar::TStatusBar

TStatusBar	See also

Creates and initializes a TStatusBar component.

__fastcall virtual TStatusBar(Classes::TComponent* AOwner);

__fastcall TStatusBar(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Do not call TStatusBar directly. Instead, use the keyword new, which returns an indirect reference to the new status bar. TStatusBar objects placed on a form at design time are created automatically.

Pass a single component as a parameter to provide the status bar with an owner that is responsible for freeing the control. This is the most commonly used constructor syntax.

To embed the status bar in a non-VCL window, pass a window handle as a parameter. This syntax is useful when the status bar is implemented as an ActiveX control.

The TStatusBar method creates a status bar along with its canvas and status panels.


TStatusBar::~TStatusBar

TStatusBar	See also

Destroys the TStatusBar and frees its memory.

__fastcall virtual ~TStatusBar(void);

Description

Do not call ~TStatusBar directly. Instead, use the delete keyword on the object, which causes ~TStatusBar to be invoked automatically.

~TStatusBar destroys the status bar along with its canvas and status panels.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TSynchroObject

Hierarchy	Methods	See also

TSynchroObject is the base class for all thread synchronization objects.

Unit

syncobjs

Description

Use TSynchroObject as a base class when defining an object that coordinates the execution of different threads in a multi-threaded application. Synchronization objects include critical sections that temporarily block the execution of other threads which may interfere with the successful completion of a section of code, and event objects that allow threads to signal when critical events have occurred.


TSynchroObject methods

TSynchroObject	Alphabetically

In TSynchroObject

~TSynchroObject

Acquire

Release

TSynchroObject

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TSynchroObject methods

TSynchroObject	By object

~TSynchroObject

Acquire

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Release

SafeCallException

TSynchroObject


TSynchroObject::Acquire

TSynchroObject	See also

Provides the interface for a method that devotes the synchronization object to a thread.

virtual void __fastcall Acquire(void);

Description

Call Acquire from the thread that wishes to use the synchronization object. The Acquire method for TSynchroObject does nothing other than provide the interface for a method that can start the synchronization object working on behalf of the calling thread.


TSynchroObject::Release

TSynchroObject	See also

Provides the interface for a method that releases the synchronization object for use by other threads.

virtual void __fastcall Release(void);

Description

Call Release from a thread that is finished using the synchronization object. The Release method for TSynchroObject does nothing other than provide the interface for a method that can unbind the synchronization object from the calling thread.


TSynchroObject::TSynchroObject

TSynchroObject

Creates a new TSynchroObject object.

__fastcall TSynchroObject(void) : System::TObject() { }

Description

Do not create instances of TSynchroObject, which does nothing except provide the interface for acquiring and releasing a synchronization resource. Instead, create the appropriate descendant of TSynchroObject.


TSynchroObject::~TSynchroObject

TSynchroObject

~TSynchroObject frees the memory associated with the TSynchroObject object.

__fastcall virtual ~TSynchroObject(void) { }

Description

Do not call ~TSynchroObject directly. Instead, use the delete keyword on the object, which causes ~TSynchroObject to be invoked automatically.


Hierarchy

TObject


THTMLTableAttributes

Hierarchy	Properties	Methods	Events	See also

THTMLTableAttributes represents the display attributes of an HTML table tag.

Unit

httpapp

Description

Use THTMLTableAttributes to describe the desired appearance of an HTML table. The properties of the THTMLTableAttributes object correspond to the options that can be added to the HTML table tag. When the attributes of all the parts of the HTML table have been specified, an HTML producer object creates the HTML commands to specify the table as described.


THTMLTableAttributes properties

THTMLTableAttributes	Alphabetically	Legend

In THTMLTableAttributes

Align

BgColor

Border

CellPadding

CellSpacing

Width

Derived from THTMLTagAttributes

Custom

Producer


THTMLTableAttributes properties

THTMLTableAttributes	By object	Legend

Align

BgColor

Border

CellPadding

CellSpacing

Custom

Producer

Width


THTMLTableAttributes::Align

THTMLTableAttributes 	See also

Specifies the alignment of the table within the HTML document.

enum THTMLAlign { haDefault, haLeft, haRight, haCenter };

__property THTMLAlign Align = {read=FAlign, write=SetAlign, default=0};

Description

Set Align to indicate the desired alignment of the table within the HTML document, or within the cell of a surrounding HTML table object. Align indicates the desired value of the Align option of the HTML table tag.

The default value of Align is haDefault, which means the web browser that reads the HTML document positions the HTML table where it wants. Align can take any of the following values:

Value	Meaning

haDefault	The web browser can position the HTML table where it wants.

haLeft	Web browsers position the HTML table with its left edge on the left edge of the HTML document or HTML table cell in which it appears.

haRight	Web browsers position the HTML table with its right edge on the right edge of the HTML document or HTML table cell in which it appears.

haCenter	Web browsers center the HTML table within the HTML document or HTML table cell in which it appears.


THTMLTableAttributes::BgColor

THTMLTableAttributes	See also

Specifies the background color of the HTML table.

__property System::AnsiString BgColor = {read=FBgColor, write=SetBGColor};

Description

Use BgColor to indicate the desired background color of the HTML table. The value of BgColor is the name of color. This can be one of the following strings:

Aqua	Black	Blue
Fuschia	Gray	Green
Lime	Maroon	Navy
Olive	Purple	Red
Silver	Teal	White
Yellow
Use the BgColor property of the HTML attributes objects for the pieces of the table for more involved color effects.


THTMLTableAttributes::Border

THTMLTableAttributes	See also

Specifies the thickness of the border drawn around the HTML table.

__property int Border = {read=FBorder, write=SetBorder, default=-1};

Description

Set Border to specify whether a border should be drawn around the table, and if so, how thick it should be. The thickness specified by any particular value of border depends on the web browser that views the HTML table. For any browser, however, larger numbers indicate thicker borders. A value of -1 indicates that no border should be drawn around the table.


THTMLTableAttributes::CellPadding

THTMLTableAttributes	See also

Specifies the amount of space to leave around the contents of each cell in the HTML table.

__property int CellPadding = {read=FCellPadding, write=SetCellPadding, default=-1};

Description

Set CellPadding to specify how many pixels of whitespace should appear between a cell’s contents and the edges of the cell. A value of -1 indicates that the web browser should decide how to pad the cells of the HTML table.


THTMLTableAttributes::CellSpacing

THTMLTableAttributes	See also

Specifies the amount of space to leave between cells in the HTML table.

__property int CellSpacing = {read=FCellSpacing, write=SetCellSpacing, default=-1};

Description

Set CellSpacing to specify how many pixels of whitespace should appear between the cells in the table. A value of -1 indicates that the web browser should decide how to separate the cells of the HTML table.

Note:	CellSpacing refers to the whitespace between cells in an HTML table, not the thickness of the lines drawn to separate rows and columns.


THTMLTableAttributes::Width

THTMLTableAttributes	See also

Specifies the width of the entire HTML table.

__property int Width = {read=FWidth, write=SetWidth, default=100};

Description

Set Width to indicate the desired width of the HTML table as a percentage of the width of the web browser window. If the value of Width is too small for the contents of the table, the web browser will ignore this property.

The default value of Width is 100, meaning the table will span the entire browser window. In this case, the value of the Align property is meaningless.


THTMLTableAttributes events

THTMLTableAttributes	Alphabetically

Derived from THTMLTagAttributes

OnChange


THTMLTableAttributes events

THTMLTableAttributes	By object

OnChange


THTMLTableAttributes methods

THTMLTableAttributes	Alphabetically	Legend

In THTMLTableAttributes

~THTMLTableAttributes

AssignTo

RestoreDefaults

THTMLTableAttributes

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableAttributes methods

THTMLTableAttributes	By object	Legend

~THTMLTableAttributes

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

THTMLTableAttributes


THTMLTableAttributes::AssignTo

THTMLTableAttributes	See also

Copies the properties of a THTMLTableAttributes object to another THTMLTableAttributes object.

virtual void __fastcall AssignTo(Classes::TPersistent* Dest);

Description

Applications can not call the protected AssignTo method. To assign the properties of a THTMLTableAttributes object to another object, use the Assign method of the destination object.

When the Assign method of another object specifies a THTMLTableAttributes object as the source of the assignment, the AssignTo method of the THTMLTableAttributes object is called. AssignTo checks whether the Dest parameter is another THTMLTableAttributes object, and if so, copies the values of the Align, Border, CellSpacing, CellPadding, and Width properties. If Dest is any other class of object, the parent class’s method is called.

Note:	AssignTo does not copy the Custom property.


THTMLTableAttributes::THTMLTableAttributes

THTMLTableAttributes	See also

Creates an instance of THTMLTableAttributes.

__fastcall THTMLTableAttributes(TCustomContentProducer* Producer);

Description

Do not call THTMLTableAttributes to create and initialize a THTMLTableAttributes object. Instead, use the new keyword, passing the content producer (Usually a TDataSetTableProducer or TQueryTableProducer) that uses the THTMLTableAttributes object as an argument.

After calling the parent class’s constructor, THTMLTableAttributes initializes

•	Width to a value of 100.

•	Border to a value of -1.

•	CellPadding to a value of -1.

•	CellSpacing to a value of -1.


THTMLTableAttributes::RestoreDefaults

THTMLTableAttributes	See also

Changes all properties of the table attributes object back to their initial settings.

virtual void __fastcall RestoreDefaults(void);

Description

Call RestoreDefaults to undo any changes that were made to the table attributes either programmatically, or using the response editor at design time. RestoreAttributes sets

•	Align to haDefault;

•	Border, CellPadding, and CellSpacing to -1;

•	Custom to an empty string.

•	Width to 100;


THTMLTableAttributes::~THTMLTableAttributes

THTMLTableAttributes

Frees the memory associated with the THTMLTableAttributes object.

__fastcall virtual ~THTMLTableAttributes(void) { }

Description

Do not call ~THTMLTableAttributes directly. Instead, use the delete keyword on the object, which causes ~THTMLTableAttributes to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

THTMLTagAttributes


THTMLTableCellAttributes

Hierarchy	Properties	Methods	Events	See also

THTMLTableCellAttributes represents the display attributes of an HTML table cell tag.

Unit

httpapp

Description

Use THTMLTableCellAttributes to describe the desired appearance of a cell in an HTML table. The properties of the THTMLTableCellAttributes object correspond to the options that can be added to the HTML table data tag (TD). When the attributes of all the parts of the HTML table have been specified, an HTML producer object creates the HTML commands to specify the table as described.


THTMLTableCellAttributes properties

THTMLTableCellAttributes	Alphabetically	Legend

Derived from THTMLTableElementAttributes

Align

BgColor

VAlign

Derived from THTMLTagAttributes

Custom

Producer


THTMLTableCellAttributes properties

THTMLTableCellAttributes	By object	Legend

Align

BgColor

Custom

Producer

VAlign


THTMLTableCellAttributes events

THTMLTableCellAttributes	Alphabetically

Derived from THTMLTagAttributes

OnChange


THTMLTableCellAttributes events

THTMLTableCellAttributes	By object

OnChange


THTMLTableCellAttributes methods

THTMLTableCellAttributes	Alphabetically

In THTMLTableCellAttributes

~THTMLTableCellAttributes

THTMLTableCellAttributes

Derived from THTMLTableElementAttributes

RestoreAttributes

Derived from THTMLTagAttributes

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableCellAttributes methods

THTMLTableCellAttributes	By object

~THTMLTableCellAttributes

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreAttributes

SafeCallException

THTMLTableCellAttributes


THTMLTableCellAttributes::THTMLTableCellAttributes

THTMLTableCellAttributes

Creates a new THTMLTableCellAttributes object.

__fastcall THTMLTableCellAttributes(TCustomContentProducer* Producer) : Httpapp::THTMLTableElementAttributes(Producer) { }

Description

Do not call THTMLTableCellAttributes directly in an application. Instead, use the new keyword, passing as an argument the content producer that will use the new attributes object.


THTMLTableCellAttributes::~THTMLTableCellAttributes

THTMLTableCellAttributes

~THTMLTableCellAttributes frees the memory associated with the THTMLTableCellAttributes object.

__fastcall virtual ~THTMLTableCellAttributes(void) { }

Description

Do not call ~THTMLTableCellAttributes directly. Instead, use the delete keyword on the object, which causes ~THTMLTableCellAttributes to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

THTMLTagAttributes

THTMLTableElementAttributes


 TTabControl

Hierarchy	Properties	Methods	Events	See also

TTabControl is a tab set that has the appearance of notebook dividers.

Unit

comctrls

Description

Use TTabControl to add a control with multiple tab settings to a form. Unlike a page control, TTabControl is not made up of several pages that contain different controls. Instead, TTabControl is a single object. When the current tab changes, the tab control must directly update its contents to reflect the change in an OnChange event handler.

Disabling a TTabControl object disables all tabs because it is one control. To disable individual tabs, use TPageControl and disable the individual TTabSheet controls that represent the pages.


TTabControl properties

TTabControl	Alphabetically	Legend

Derived from TCustomTabControl

DisplayRect

HotTrack

MultiLine

ScrollOpposite

TabHeight

TabIndex

TabPosition

Tabs

TabWidth

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TTabControl properties

TTabControl	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

ComponentState

Components

ComponentStyle

ControlCount

ControlState

Controls

ControlStyle

Cursor

DesignInfo

DisplayRect

DragCursor

DragMode

Enabled

Font

Handle

Height

HelpContext

Hint

HotTrack

Left

MultiLine

Name

Owner

ParentFont

ParentShowHint

Parent

ParentWindow

PopupMenu

ScrollOpposite

ShowHint

Showing

TabHeight

TabIndex

TabOrder

TabPosition

Tabs

TabStop

TabWidth

Tag

Top

VCLComObject

Visible

Width

WindowProc


TTabControl events

TTabControl	Alphabetically	Legend

Derived from TCustomTabControl

OnChange

OnChanging

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TTabControl events

TTabControl	By object	Legend

OnChange

OnChanging

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TTabControl methods

TTabControl	Alphabetically

In TTabControl

~TTabControl

TTabControl

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTabControl methods

TTabControl	By object

~TTabControl

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TTabControl

Update

UpdateControlState


TTabControl::TTabControl

TTabControl

Creates a new TTabControl object.

__fastcall virtual TTabControl(Classes::TComponent* AOwner) : Comctrls::TCustomTabControl(AOwner) { }

__fastcall TTabControl(HWND ParentWindow) : Comctrls::TCustomTabControl(ParentWindow) { }

Description

Call TTabControl indirectly, using the new keyword, to create a tab control at runtime. Tab controls added to forms at design time are added automatically.

Pass a single Component as a parameter to provide the tab control with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the tab control in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TTabControl::~TTabControl

TTabControl

~TTabControl frees the memory associated with the TTabControl object.

__fastcall virtual ~TTabControl(void) { }

Description

Do not call ~TTabControl directly. Instead, use the delete keyword on the object, which causes ~TTabControl to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomTabControl


THTMLTableElementAttributes

Hierarchy	Properties	Methods	Events	See also

THTMLTableElementAttributes is the common base class for objects that describe the display attributes of parts of an HTML table.

Unit

httpapp

Description

Use the properties of THTMLTableElementAttributes to describe the desired appearance of a piece of an HTML table. The properties of THTMLTableElementAttributes correspond to the common options that can be added to the tags for the parts of the HTML table. When the attributes of all the parts of the HTML table have been specified, an HTML producer object creates the HTML commands to specify the table as described.


THTMLTableElementAttributes properties

THTMLTableElementAttributes	Alphabetically	Legend

In THTMLTableElementAttributes

Align

BgColor

VAlign

Derived from THTMLTagAttributes

Custom

Producer


THTMLTableElementAttributes properties

THTMLTableElementAttributes	By object	Legend

Align

BgColor

Custom

Producer

VAlign


THTMLTableElementAttributes::Align

THTMLTableElementAttributes	See also

Specifies the horizontal alignment of the contents of the HTML table element.

enum THTMLAlign { haDefault, haLeft, haRight, haCenter };

__property THTMLAlign Align = {read=FAlign, write=SetAlign, default=0};

Description

Set Align to indicate the desired horizontal alignment of the contents of the cell or cells indicated by the table element. Align indicates the desired value of the Align option of the HTML tag for the table element.

The default value of Align is haDefault, which means the web browser that reads the HTML document horizontally positions the contents of the table element wherever it wishes. Align can take any of the following values:

Value	Meaning

haDefault	The web browser can position the contents of cells in the table element anywhere horizontally.

haLeft	The web browser positions the contents of cells in the table element so that they appear lined up on the left.

haRight	The web browser positions the contents of cells in the table element so that they appear lined up on the right.

haCenter	The web browser centers the contents horizontally in the cells in the table element.

The Align property of table data cells or header cells overrides the Align property of the table row in which they appear.


THTMLTableElementAttributes::BgColor

THTMLTableElementAttributes	See also

Specifies the background color of the HTML table element.

__property System::AnsiString BgColor = {read=FBgColor, write=SetBGColor};

Description

Use BgColor to indicate the desired background color of the HTML table element. The value of BgColor is the name of color. This can be one of the following strings:

Aqua	Black	Blue
Fuschia	Gray	Green
Lime	Maroon	Navy
Olive	Purple	Red
Silver	Teal	White
Yellow
Use the BgColor property of the THTMLTableAttributes object to set a background color for the entire table. Use the BgColor property of the table element attributes object to make a table element stand out from the rest of the table.


THTMLTableElementAttributes::VAlign

THTMLTableElementAttributes	See also

Specifies the vertical alignment of the contents of the HTML table element.

enum THTMLVAlign { haVDefault, haTop, haMiddle, haBottom, haBaseline };

__property THTMLVAlign VAlign = {read=FVAlign, write=SetVAlign, default=0};

Description

Set VAlign to indicate the desired vertical alignment of the contents of the HTML table element. VAlign indicates the desired value of the VAlign option of the HTML tag for the table element.

The default value of VAlign is haVDefault, which means the web browser that reads the HTML document positions the contents of cells in the table element wherever it wishes vertically. VAlign can take any of the following values:

Value	Meaning

haVDefault	The web browser can position the contents of cells in the table element anywhere vertically.

haTop	The web browser positions the contents of cells in the table element so that they appear at the top.

haMiddle	The web browser centers the contents of cells in the table element vertically.

haBottom	The web browser positions the contents of cells in the table element so that they appear at the bottom.

haBaseline	The web browser positions the contents of every table element within a row so that they all share the same baseline for the first line of text.

The VAlign property of table data cells or header cells overrides the VAlign property of the table row in which they appear.


THTMLTableElementAttributes events

THTMLTableElementAttributes	Alphabetically

Derived from THTMLTagAttributes

OnChange


THTMLTableElementAttributes events

THTMLTableElementAttributes	By object

OnChange


THTMLTableElementAttributes methods

THTMLTableElementAttributes	Alphabetically	Legend

In THTMLTableElementAttributes

~THTMLTableElementAttributes

AssignTo

RestoreDefaults

THTMLTableElementAttributes

Derived from THTMLTagAttributes

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableElementAttributes methods

THTMLTableElementAttributes	By object	Legend

~THTMLTableElementAttributes

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

THTMLTableElementAttributes


THTMLTableElementAttributes::AssignTo

THTMLTableElementAttributes	See also

Copies the properties of a THTMLTableElementAttributes object to another THTMLTableElementAttributes object.

virtual void __fastcall AssignTo(Classes::TPersistent* Dest);

Description

Applications can not call the protected AssignTo method. To assign the properties of a THTMLTableElementAttributes object to another object, use the Assign method of the destination object.

When the Assign method of another object specifies a THTMLTableElementAttributes object as the source of the assignment, the AssignTo method of the THTMLTableElementAttributes object is called. AssignTo checks whether the Dest parameter is another THTMLTableElementAttributes object, and if so, copies the values of the BgColor, Align and VAlign properties. If Dest is any other class of object, the parent class’s method is called.

Note:	AssignTo does not copy the Custom property.


THTMLTableElementAttributes::RestoreDefaults

THTMLTableElementAttributes	See also

Changes all properties of the attributes object back to their initial settings.

virtual void __fastcall RestoreDefaults(void);

Description

Call RestoreDefaults to undo any changes that were made to the table element attributes either programmatically, or using the Object Inspector at design time. RestoreAttributes sets

•	Align to haDefault, and VAlign to haVDefault.

•	BgColor to an empty string.

•	Custom to an empty string.


THTMLTableElementAttributes::THTMLTableElementAttributes

THTMLTableElementAttributes

Creates a new THTMLTableElementAttributes object.

__fastcall THTMLTableElementAttributes(TCustomContentProducer* Producer) : Httpapp::THTMLTagAttributes(Producer) { }

Description

Do not call THTMLTableElementAttributes directly in an application. Instead, use the new keyword, passing as an argument the content producer that will use the new attributes object.


THTMLTableElementAttributes::~THTMLTableElementAttributes

THTMLTableElementAttributes

~THTMLTableElementAttributes frees the memory associated with the THTMLTableElementAttributes object.

__fastcall virtual ~THTMLTableElementAttributes(void) { }

Description

Do not call ~THTMLTableElementAttributes directly. Instead, use the delete keyword on the object, which causes ~THTMLTableElementAttributes to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent

THTMLTagAttributes


THTMLTableHeaderAttributes

Hierarchy	Properties	Methods	Events	See also

THTMLTableHeaderAttributes represents the display attributes of the header tag in an HTML table.

Unit

httpapp

Description

Use THTMLTableHeaderAttributes to describe the desired appearance of a header cell in an HTML table. The properties of the THTMLTableHeaderAttributes object correspond to the options that can be added to the HTML header tag (TH). When the attributes of all the parts of the HTML table have been specified, the HTML content producer creates the HTML commands to specify the table as described.


THTMLTableHeaderAttributes properties

THTMLTableHeaderAttributes	Alphabetically	Legend

In THTMLTableHeaderAttributes

Caption

Derived from THTMLTableElementAttributes

Align

BgColor

VAlign

Derived from THTMLTagAttributes

Custom

Producer


THTMLTableHeaderAttributes properties

THTMLTableHeaderAttributes	By object	Legend

Align

BgColor

Caption

Custom

Producer

VAlign


THTMLTableHeaderAttributes::Caption

THTMLTableHeaderAttributes	See also

Represents the text that appears in the header cell.

__property System::AnsiString Caption = {read=FCaption, write=SetCaption};

Description

Set the Caption property to provide a caption for the column that contains the header cell. If the header cell is used by a dataset table producer or a query table producer, the Caption property overrides the field name that would label the column by default.


THTMLTableHeaderAttributes events

THTMLTableHeaderAttributes	Alphabetically

Derived from THTMLTagAttributes

OnChange


THTMLTableHeaderAttributes events

THTMLTableHeaderAttributes	By object

OnChange


THTMLTableHeaderAttributes methods

THTMLTableHeaderAttributes	Alphabetically

In THTMLTableHeaderAttributes

~THTMLTableHeaderAttributes

RestoreDefaults

THTMLTableHeaderAttributes

Derived from THTMLTagAttributes

RestoreDefaults

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableHeaderAttributes methods

THTMLTableHeaderAttributes	By object

~THTMLTableHeaderAttributes

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

THTMLTableHeaderAttributes


THTMLTableHeaderAttributes::RestoreDefaults

THTMLTableHeaderAttributes	See also

Changes all properties of the attributes object back to their initial settings.

virtual void __fastcall RestoreDefaults(void);

Description

Call RestoreDefaults to undo any changes that were made to the table element attributes either programmatically, or using the Object Inspector at design time. RestoreAttributes sets

•	Align to haDefault, and VAlign to haVDefault.

•	BgColor to an empty string.

•	Caption to an empty string.

•	Custom to an empty string.


THTMLTableHeaderAttributes::THTMLTableHeaderAttributes

THTMLTableHeaderAttributes

Creates a new THTMLTableHeaderAttributes object.

__fastcall THTMLTableHeaderAttributes(TCustomContentProducer* Producer) : Httpapp::THTMLTableElementAttributes(Producer) { }

Description

Do not call THTMLTableHeaderAttributes directly. Instead, use the new keyword, passing as an argument the content producer that uses the attributes object.


THTMLTableHeaderAttributes::~THTMLTableHeaderAttributes

THTMLTableHeaderAttributes

~THTMLTableHeaderAttributes frees the memory associated with the THTMLTableHeaderAttributes object.

__fastcall virtual ~THTMLTableHeaderAttributes(void) { }

Description

Do not call ~THTMLTableHeaderAttributes directly. Instead, use the delete keyword on the object, which causes ~THTMLTableHeaderAttributes to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

THTMLTagAttributes

THTMLTableElementAttributes


 TTable

Hierarchy	Properties	Methods	Events	See also

TTable is a dataset component that encapsulates a database table.

Unit

dbtables

Description

Use TTable to access data in a single database table using the Borland Database Engine (BDE). TTable provides direct access to every record and field in an underlying database table, whether it is from Paradox, dBASE, Access, FoxPro, an ODBC-compliant database, or an SQL database on a remote server, such as InterBase, Oracle, Sybase, MS-SQL Server, Informix, or DB2. A table component can also work with a subset of records within a database table using ranges and filters.

At design time, you can create, delete, update, or rename the database table connected to a TTable by right-clicking on the TTable and using the pop-up menu.


TTable properties

TTable	Alphabetically	Legend

In TTable

CanModify

DataSource

Exclusive

FieldDefs

IndexDefs

IndexFieldCount

IndexFieldNames

IndexFields

IndexFiles

IndexName

KeyExclusive

KeyFieldCount

MasterFields

MasterSource

ReadOnly

StoreDefs

TableLevel

TableName

TableType

Derived from TDBDataSet

Database

DatabaseName

DBHandle

DBLocale

DBSession

Provider

SessionName

UpdateMode

Derived from TBDEDataSet

CacheBlobs

CachedUpdates

ExpIndex

Filter

Filtered

FilterOptions

Handle

KeySize

Locale

RecNo

RecordCount

RecordSize

UpdateObject

UpdateRecordTypes

UpdatesPending

Derived from TDataSet

Active

AutoCalcFields

BOF

Bookmark

Constraints

DefaultFields

Designer

EOF

FieldCount

Fields

FieldValues

Found

Modified

Name

State

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TTable properties

TTable	By object	Legend

Active

AutoCalcFields

BOF

Bookmark

CacheBlobs

CachedUpdates

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

Constraints

Database

DatabaseName

DataSource

DBHandle

DBLocale

DBSession

DefaultFields

Designer

DesignInfo

EOF

Exclusive

ExpIndex

FieldCount

FieldDefs

Fields

FieldValues

Filter

Filtered

FilterOptions

Found

Handle

IndexDefs

IndexFieldCount

IndexFieldNames

IndexFields

IndexFiles

IndexName

KeyExclusive

KeyFieldCount

KeySize

Locale

MasterFields

MasterSource

Modified

Name

Owner

Provider

ReadOnly

RecNo

RecordCount

RecordSize

SessionName

State

StoreDefs

TableLevel

TableName

TableType

Tag

UpdateMode

UpdateObject

UpdateRecordTypes

UpdatesPending

VCLComObject


TTable::CanModify

TTable	See also

Indicates whether an application can insert, edit, or delete data in a table.

__property bool CanModify = {read=GetCanModify, nodefault};

Description

Check the status of CanModify to determine if an application can modify a dataset in any way. If CanModify is true, the dataset can be modified. If CanModify is false, the table is read-only.

CanModify is set automatically when an application opens a table. If the ReadOnly property of a table component is true, then CanModify is set to false. CanModify can also be false because

•	Another application currently has exclusive write access to the table.

•	The table is read-only by database design.

Note:	Even if CanModify is true, it is not a guarantee that a user will be able to insert or update records in a table. Other factors may come in to play, for example, SQL access privileges.


TTable::DataSource

TTable	See also

Specifies the data source for the table.

__property Db::TDataSource* DataSource = {read=GetDataSource, write=SetDataSource};

Description

Use the DataSource property to determine the data source currently assigned to the table. When an application sets the DataSet property for a DataSource component to the name of this table component, the DataSource property for the table is automatically updated to the name of the data source component that uses it.


TTable::Exclusive

TTable	See also 	Example

Enables an application to gain sole access to a Paradox or dBASE table.

__property bool Exclusive = {read=FExclusive, write=SetExclusive, default=0};

Description

Use Exclusive to prevent other applications from accessing a Paradox or dBASE table while this application is using it. Before opening the table, set Exclusive to true.

When Exclusive is true, then when the application successfully opens the table, no other application can access it. If the table for which the application has requested exclusive access is already in use by another application, an exception is raised. To handle such exceptions, write an exception handler.

A table must be closed before changing the setting of the Exclusive property. Do not set Exclusive to true at design time if you also intend to set the Active property to true at design time. In this case an exception is raised because the table is already in use by the IDE.

Note:	An application can attempt to set Exclusive to true for SQL tables, but some SQL servers do not support exclusive table-locking. Others may grant an exclusive read/write lock, but still permit read-only access to other applications. For more information about exclusive locking of database tables for a specific server, see the server’s documentation.


TTable::Exists

TTable	See also 	Example

Indicates whether the table exists.

__property bool Exists = {read=GetExists, nodefault};

Description

Read Exists at runtime to determine whether a database table exists. This property is read-only.


TTable::FieldDefs

TTable	See also

Points to the list of field definitions for the table.

__property FieldDefs  = {stored=FStoreDefs};

Description

FieldDefs points to an internal list of field definitions for a dataset. If FieldDefs is updated or manually edited, the StoreDefs property becomes true.


TTable::IndexDefs

TTable	See also 	Example

Contains information about the indexes for a table.

__property Db::TIndexDefs* IndexDefs = {read=FIndexDefs, write=SetIndexDefs, stored=FStoreDefs};

Description

IndexDefs is an array of index items, each of which describes an available index for the table. Ordinarily an application accesses or specifies indexes through the IndexFieldNames or IndexFields properties. If IndexDefs is updated or manually edited, the StoreDefs property becomes true.

Note:	The index items in IndexDefs may not always reflect the current indexes available for a table. Before examining IndexDefs, call its Update method to refresh the item list.


TTable::IndexFieldCount

TTable	See also 	Example

Indicates the number of fields that comprise the current key.

__property int IndexFieldCount = {read=GetIndexFieldCount, nodefault};

Description

Examine IndexFieldCount to determine the number of fields that comprise the current key. For indexes based on a single column, IndexFieldCount returns 1. For multi-column indexes, IndexFieldCount indicates the number of fields upon which the index is based.


TTable::IndexFieldNames

TTable	See also

Lists the columns to use as an index for a table.

__property System::AnsiString IndexFieldNames = {read=GetIndexFieldNames, write=SetIndexFieldNames}

Description

Use IndexFieldNames as an alternative method of specifying the index to use for a table. In IndexFieldNames specify the name of each column to use as an index for a table. Ordering of column names is significant. Separate names with semicolon.

For Paradox and dBASE any column names specified in IndexFieldNames must already be indexed. For SQL-based tables, the specified columns need not be indexed.

Note:	The IndexFieldNames and IndexName properties are mutually exclusive. Setting one clears the other.


TTable::IndexFields

TTable	See also 	Example

Retrieves or sets a field for an index.

__property Db::TField* IndexFields[int Index] = {read=GetIndexField, write=SetIndexField};

Description

IndexFields provides a zero-based array of field objects, each of which corresponds to a field in the current index. Index is an ordinal value indicating the position of a field in the index. The first field in the index is IndexFields[0], the second is IndexFields[1], and so on.

Note:	Do not set IndexFields directly. Instead use the IndexFieldNames property to order datasets on the fly at runtime.


TTable::IndexFiles

TTable	See also

Specifies one or more dBASE index file to use for a dBASE table that uses non-production indexes.

__property Classes::TStrings* IndexFiles = {read=FIndexFiles, write=SetIndexFiles};

Description

Use IndexFiles to specify dBASE index files to make available for the table that uses non-production indexes. A dBASE index file can contain multiple indexes. Each index in an index file becomes available as a selection for the IndexName property which specifies the actual index to use at any given time.

When index files are added to the list of available indexes, the table component opens them. Insertions and modifications made to the table are maintained in the index files. When files are removed from the list, the table component closes them, and they are no longer maintained.

Note:	At design time, use the Object Inspector to add or remove index file names for the IndexFiles property. At runtime multiple index files can be specified by setting IndexFiles to a string that contains a list of semicolon-delimited file names.


TTable::IndexName

TTable	See also 	Example

Identifies a secondary index for the table.

__property System::AnsiString IndexName = {read=GetIndexName, write=SetIndexName};

Description

Use IndexName to specify an alternative index for a table. Otherwise, if IndexName is empty, a table’s sort order is based on its primary index, or, for dBASE tables, on its physical record order.

If IndexName contains a valid index name, then that index is used to determine sort order of records. For dBASE tables, an index name supplied to the IndexName property must either reside in the table's master index file, or in another index file already specified in the IndexFiles property.

Note:	IndexFieldNames and IndexName are mutually exclusive. Setting one clears the other.


TTable::KeyExclusive

TTable	See also 	Example

Specifies how the upper and lower boundaries for a range should be interpreted.

__property bool KeyExclusive = {read=GetKeyExclusive, write=SetKeyExclusive, nodefault};

Description

Use KeyExclusive to specify whether or not a range includes or excludes the records that match the specified starting and ending values for a range. By default, KeyExclusive is true, meaning that matching values are not included.

To restrict a range to those records that are greater than the specified starting value and less than the specified ending value, set KeyExclusive to true. To include the endpoints in the range, set KeyExclusive to false.


TTable::KeyFieldCount

TTable	See also

Specifies the number of fields to use when conducting a partial key search on a multi-field key.

__property int KeyFieldCount = {read=GetKeyFieldCount, write=SetKeyFieldCount, nodefault};

Description

Use KeyFieldCount to limit a search based on a multi-field key to a consecutive sub-set of those fields. KeyFieldCount is zero-based. For example, if the primary key for a dataset consists of three-fields, a partial-key search can be conducted using only the first fields in the key by setting KeyFieldCount to 0.

Note:	Searches are only conducted based on consecutive key fields beginning with the first field in the key. For example if a key consists of three fields, an application can set KeyFieldCount to 0 to search on the first field, 1 to search on the first and second fields, or 2 to search on all fields. By default KeyFieldCount is initially set to include all fields in a search.


TTable::MasterFields

TTable	See also 	Example

Specifies one or more fields in a master table to link with corresponding fields in this table in order to establish a master-detail relationship between the tables.

__property System::AnsiString MasterFields = {read=GetMasterFields, write=SetMasterFields};

Description

Use MasterFields after setting the MasterSource property to specify the names of one or more fields to use in establishing a detail-master relationship between this table and the one specified in MasterSource.

MasterFields is a string containing one or more field names in the master table. Separate field names with semicolons.

Each time the current record in the master table changes, the new values in those fields are used to select corresponding records in this table for display.

Note:	At design time, use the Field Link designer to establish the master-detail relationship between two tables.


TTable::MasterSource

TTable	See also 	Example

Specifies the name of the data source component for the dataset to use as a master table in establishing a detail-master relationship between this table and another one.

__property Db::TDataSource* MasterSource = {read=GetDataSource, write=SetDataSource};

Description

Use MasterSource to specify the name of the data source component whose DataSet property identifies a dataset to use as a master table in establishing a detail-master relationship between this table and another one.

Note:	At design time choose an available data source from the MasterSource property’s drop-down list in the Object Inspector.

After setting the MasterSource property, specify which fields to use in the master table by setting the MasterFields property. At runtime each time the current record in the master table changes, the new values in those fields are used to select corresponding records in this table for display.

Note:	At design time, use the Field Link designer to establish the master-detail relationship between two tables.


TTable::ReadOnly

TTable	See also	Example

Specifies whether a table is read-only for this application.

__property bool ReadOnly = {read=FReadOnly, write=SetReadOnly, default=0};

Description

Use the ReadOnly property to prevent users from updating, inserting, or deleting data in the table. By default, ReadOnly is false, meaning users can potentially alter a table’s data.

Note:	Even if ReadOnly is false, users may not be able to modify or add data to a table. Other factors, such as insufficient SQL privileges for the application or its current user may prevent successful alterations.

To guarantee that users cannot modify or add data to a table,

1	Set the Active property to false.

2	Set ReadOnly to true.

When ReadOnly is true, the table’s CanModify property is false.


TTable::StoreDefs

TTable	See also

Indicates whether the table's field and index definitions persist with the data module or form.

__property bool StoreDefs = {read=FStoreDefs, write=FStoreDefs, default=0};

Description

If StoreDefs is true, the table's index and field definitions are stored with the data module or form. Setting StoreDefs to true makes the CreateTable method into a one-step procedure that creates fields, indexes, and validity checks at runtime.

StoreDefs is false by default. It becomes true whenever FieldDefs or IndexDefs is updated or edited manually; to prevent edited (or imported) definitions from being stored, reset StoreDefs to false.


TTable::TableLevel

TTable	See also

Specifies the Borland Database Engine (BDE) driver-dependent table level.

__property int TableLevel = {read=GetTableLevel, write=FTableLevel, nodefault};

Description

Use TableLevel when creating a table to specify that the table associated with this dataset requires a specific level of BDE driver. If TableLevel is 0, the default, this property is ignored.

For more information about BDE driver table level specification, see the online BDE help file, BDE32.HLP.


TTable::TableName

TTable	See also 	Example

Indicates the name of the database table that this component encapsulates.

__property System::AnsiString TableName = {read=FTableName, write=SetTableName};

Description

Use TableName to specify the name of the database table this component encapsulates. To set TableName to a meaningful value, the DatabaseName property should already be set. If DatabaseName is set at design time, then select a valid table name from the TableName drop-down list in the Object Inspector.

Note:	To set TableName, the Active property must be false.


TTable::TableType

TTable	See also 	Example

Indicates the database table structure for the table that this component encapsulates.

__property TTableType TableType = {read=FTableType, write=SetTableType, default=0};

Description

Use TableType to specify the database table structure for a dBASE, Paradox, FoxPro or ASCII table. TableType does not apply to tables for remote SQL servers. TableType can be set to any of the following values:

Value	Meaning

ttDefault	(Default) Determine table type based on file extension for the table.

ttParadox	Table is a Paradox table.

ttDBase	Table is a dBASE table.

ttFoxPro	Table is a FoxPro table.

ttASCII	Table is a text file with comma-delimited, quoted strings for each field

If TableType is set to ttDefault, the table's file-name extension determines the table type:

Extension	Meaning

DB or none	Paradox table

DBF	dBASE table

TXT	ASCII table

If TableType is ttParadox, ttDBase, ttFoxPro or ttASCII, the table type is assumed to be of the type specified, regardless of the table’s file name extension.


TTable events

TTable	Alphabetically	Legend

Derived from TBDEDataSet

OnServerYield

OnUpdateError

OnUpdateRecord

Derived from TDataSet

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError


TTable events

TTable	By object	Legend

AfterCancel

AfterClose

AfterDelete

AfterEdit

AfterInsert

AfterOpen

AfterPost

AfterScroll

BeforeCancel

BeforeClose

BeforeDelete

BeforeEdit

BeforeInsert

BeforeOpen

BeforePost

BeforeScroll

OnCalcFields

OnDeleteError

OnEditError

OnFilterRecord

OnNewRecord

OnPostError

OnServerYield

OnUpdateError

OnUpdateRecord


TTable methods

TTable	Alphabetically

In TTable

~TTable

AddIndex

ApplyRange

BatchMove

CancelRange

CloseIndexFile

CreateTable

DeleteIndex

DeleteTable

EditKey

EditRangeEnd

EditRangeStart

EmptyTable

FindKey

FindNearest

GetIndexNames

GotoCurrent

GotoKey

GotoNearest

LockTable

OpenIndexFile

RenameTable

SetKey

SetRange

SetRangeEnd

SetRangeStart

TTable

UnlockTable

Derived from TDBDataSet

CheckOpen

CloseDatabase

OpenDatabase

Derived from TBDEDataSet

ApplyUpdates

BookmarkValid

Cancel

CancelUpdates

CommitUpdates

CompareBookmarks

ConstraintCallBack

ConstraintsDisabled

CreateBlobStream

DisableConstraints

EnableConstraints

FetchAll

FlushBuffers

GetCurrentRecord

GetIndexInfo

IsSequenced

Locate

Lookup

Post

RevertRecord

UpdateStatus

Derived from TDataSet

ActiveBuffer

Append

AppendRecord

CheckBrowseMode

ClearFields

Close

ControlsDisabled

CursorPosChanged

Delete

DisableControls

Edit

EnableControls

FieldByName

FindField

FindFirst

FindLast

FindNext

FindPrior

First

FreeBookmark

GetBookmark

GetFieldList

GetFieldNames

GotoBookmark

Insert

InsertRecord

IsEmpty

IsLinkedTo

Last

MoveBy

Next

Open

Prior

Refresh

Resync

SetFields

Translate

UpdateCursorPos

UpdateRecord

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTable methods

TTable	By object

~TTable

ActiveBuffer

AddIndex

Append

AppendRecord

ApplyRange

ApplyUpdates

Assign

BatchMove

BookmarkValid

Cancel

CancelRange

CancelUpdates

CheckBrowseMode

CheckOpen

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClearFields

Close

CloseDatabase

CloseIndexFile

CommitUpdates

CompareBookmarks

ConstraintCallBack

ConstraintsDisabled

ControlsDisabled

CreateBlobStream

CreateTable

CursorPosChanged

DefaultHandler

Delete

DeleteIndex

DeleteTable

DestroyComponents

Destroying

DisableConstraints

DisableControls

Dispatch

Edit

EditKey

EditRangeEnd

EditRangeStart

EmptyTable

EnableConstraints

EnableControls

FetchAll

FieldAddress

FieldByName

FindComponent

FindField

FindFirst

FindKey

FindLast

FindNearest

FindNext

FindPrior

First

FlushBuffers

Free

FreeBookmark

FreeInstance

FreeNotification

FreeOnRelease

GetBookmark

GetCurrentRecord

GetFieldList

GetFieldNames

GetIndexInfo

GetIndexNames

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GotoBookmark

GotoCurrent

GotoKey

GotoNearest

HasParent

InheritsFrom

InitInstance

Insert

InsertComponent

InsertRecord

InstanceSize

IsEmpty

IsLinkedTo

IsSequenced

Last

Locate

LockTable

Lookup

MethodAddress

MethodName

MoveBy

NewInstance

Next

Open

OpenDatabase

OpenIndexFile

Post

Prior

Refresh

RemoveComponent

RenameTable

Resync

RevertRecord

SafeCallException

SetFields

SetKey

SetRange

SetRangeEnd

SetRangeStart

Translate

TTable

UnlockTable

UpdateCursorPos

UpdateRecord

UpdateStatus


TTable::AddIndex

TTable	See also 	Example

Creates a new index for the table.

void __fastcall AddIndex(const System::AnsiString Name, const System::AnsiString Fields, Db::TIndexOptions Options);

Description

Call AddIndex to create a new index for the table associated with a dataset. The index created with this procedure is added to the database table underlying the dataset. Name is the name of the new index. Fields is a semicolon-delimited list of the fields to include in the index. Options is a potentially restricted set of one or more of the following values:

Value	Meaning	Restrictions

ixPrimary	Create a primary index	Cannot be used with dBASE.

Cannot create more than one primary index per table.

ixUnique	Create a unique index

ixDescending	Sort in descending alphanumeric order

ixCaseInsensitive	Ignore case when sorting	Cannot be used with dBASE.

ixExpression	Create an expression index	dBASE only

Attempting to create an index using options that are not applicable to the table raises an exception.


TTable::ApplyRange

TTable	See also 	Example

Applys a range to the dataset.

void __fastcall ApplyRange(void);

Description

Call ApplyRange to cause a range established with SetRangeStart and SetRangeEnd, or EditRangeStart and EditRangeEnd, to take effect. When a range is in effect, only those records that fall within the range are available to the application for viewing and editing.


TTable::BatchMove

TTable	See also

Moves records from a dataset into this table.

int __fastcall BatchMove(TBDEDataSet* ASource, TBatchMode AMode);

Description

Call BatchMove to

•	Copy records from another table into this table.

•	Update records in this table that occur in another table.

•	Append records from another table to the end of this table.

•	Delete records in this table that occur in another table.

ASource is a dataset component containing the records to import for use in this table. AMode is one of the following:

Value	Meaning

batAppend	Append all records from the source table to the end of this table. The destination and source tables must not have records with duplicate keys.

batAppendUpdate	Append all records from the source table to the end of this table and update existing records in this table with the same records from the source table

batCopy	Copy all records from the source table into this table.

batDelete	Delete all records in this table that also appear in the source table.

batUpdate	Update existing records in this table with their counterparts in the source table.

BatchMove returns the number of records operated on.


TTable::CancelRange

TTable	See also

Removes any ranges currently in effect for the table.

void __fastcall CancelRange(void);

Description

Call CancelRange to remove a range currently applied to a table. Canceling a range reenables access to all records in the dataset.


TTable::CloseIndexFile

TTable	See also

Closes a specified dBASE non-production index file.

void __fastcall CloseIndexFile(const System::AnsiString IndexFileName);

Description

Call CloseIndexFile to shut down a specified dBASE non-production index file. IndexFileName is the name of the file to close, and is either the name of an index file previously opened with a call to OpenIndexFile or previously opened because the file’s name is listed in the IndexFiles property.

Once closed, non-production index files are no longer maintained. Subsequent changes made to the dataset are not reflected in the index.


TTable::TTable

TTable	See also

Creates an instance of a table component.

__fastcall virtual TTable(Classes::TComponent* AOwner);

Description

Call TTable to instantiate a table declared in an application if it was not placed on a form at design time. TTable calls its parent object’s constructor constructor, creates an empty index definitions list, creates an empty data link, and creates an empty list of index files.


TTable::TTable
TTable::CreateTable

TTable	See also 	Example

Builds a new table using new structure information.

void __fastcall CreateTable(void);

Description

Call CreateTable at runtime to create a table using this dataset’s current definition. CreateTable overwrites an existing table’s structure and data; to avoid overwriting an existing table, check Exists before calling CreateTable.

If the FieldDefs property contains values, these values are used to create field definitions. Otherwise the Fields property is used. One or both of these properties must contain values in order to recreate a dataset.

If the IndexDefs property contain values, these values are used to create index definitions for the dataset.


TTable::DeleteIndex

TTable	See also

Deletes a secondary index for the table.

void __fastcall DeleteIndex(const System::AnsiString Name);

Description

Call DeleteIndex to remove a secondary index for a table. Name is the name of the index to delete. DeleteIndex cannot remove a primary index.

Note:	To delete an index, an application must first open the table for exclusive access.


TTable::DeleteTable

TTable	See also 	Example

Deletes an existing database table.

void __fastcall DeleteTable(void);

Description

Call DeleteTable to delete an existing database table associated with the table component through its DatabaseName and TableName properties. A table must be closed before it can be deleted.

Warning: Deleting a table erases any data the table contains and destroys the table’s structure information.


TTable::~TTable

TTable	See also

Destroys the instance of a table.

__fastcall virtual ~TTable(void);

Description

Do not call ~TTable directly. Instead call Free to verify that the table is not already freed before calling ~TTable. ~TTable frees the index files list for the table, frees its data link, frees its index definitions, and then calls its parent object’s destructor destructor.


TTable::EditKey

TTable	See also	Example

Enables modification of the search key buffer.

void __fastcall EditKey(void);

Description

Call EditKey to put the dataset in dsSetKey state while preserving the current contents of the current search key buffer. To determine current search keys, you can use the IndexFields property to iterate over the fields used by the current index.

EditKey is especially useful when performing multiple searches where only one or two field values among many change between each search.


TTable::EditRangeEnd

TTable	See also 	Example

Enables changing the ending value for an existing range.

void __fastcall EditRangeEnd(void);

Description

Call EditRangeEnd to change the ending value for an existing range. To specify an end range value, call FieldByName after calling EditRangeEnd. After assigning a new ending value, call ApplyRange to activate the modified range.

Note:	With Paradox or dBASE tables, EditRangeEnd works only on indexed fields. With SQL databases, EditRangeEnd also works with any columns specified in the IndexFieldNames property.


TTable::EditRangeStart

TTable	See also 	Example

Enables changing the starting value for an existing range.

void __fastcall EditRangeStart(void);

Description

Call EditRangeStart to change the starting value for an existing range. To specify a start range value, call FieldByName after calling EditRangeStart. After assigning a new ending value, call ApplyRange to activate the modified range.

Note:	With Paradox or dBASE tables, EditRangeStart works only on indexed fields. With SQL databases, EditRangeStart also works with any columns specified in the IndexFieldNames property.


TTable::EmptyTable

TTable	See also 	Example

Deletes all records from the table.

void __fastcall EmptyTable(void);

Description

The EmptyTable method deletes all records from the database table specified by the DatabaseName and TableName properties.

Note:	Deletion of records can fail if the user lacks sufficient privileges to perform the delete operation.


TTable::FindKey

TTable	See also

Searches for a record containing specified field values.

bool __fastcall FindKey(const System::TVarRec * KeyValues, const int KeyValues_Size);

Description

Call FindKey to search for a specific record in a dataset. KeyValues contains a comma-delimited array of field values, called a key. Each value in the key can be a literal, a variable, a null, or NULL. If the number of values passed in KeyValues is less than the number of columns in the index used for the search, the missing values are assumed to be null.

For Paradox and dBASE tables, the key must always be an index, which can be specified in the IndexName property. If IndexName is empty, the table’s primary index.

For SQL tables, the key may correspond to a specified index in IndexName, or to a list of field names in the IndexFieldNames property.

If a search is successful, FindKey positions the cursor on the matching record and returns true. Otherwise the cursor is not moved, and FindKey returns false.


TTable::FindNearest

TTable	See also	Example

Moves the cursor to the record that most closely matches a specified set of key values.

void __fastcall FindNearest(const System::TVarRec * KeyValues, const int KeyValues_Size);

Description

Call FindNearest to move the cursor to a specific record in a dataset or to the first record in the dataset that is greater than the values specified in the KeyValues parameter. KeyValues contains a comma-delimited array of field values, called a key. If the number of values passed in KeyValues is less than the number of columns in the index used for the search, the missing values are assumed to be null.

For Paradox and dBASE tables, the key must always be an index, which can be specified in the IndexName property. If IndexName is empty, the table’s primary index.

For SQL tables, the key may correspond to a specified index in IndexName, or to a list of field names in the IndexFieldNames property.

FindNearest positions the cursor either on a record that exactly matches the search criteria, or on the first record whose values are greater than those specified in the search criteria. KeyExclusive also affects the boundary conditions of ranges and will affect the record selected by FindNearest.


TTable::GetIndexNames

TTable	See also

Retrieves a list of available indexes for a table.

void __fastcall GetIndexNames(Classes::TStrings* List);

Description

Call GetIndexNames to retrieve a list of all available indexes for a table. List is a string list object, created and maintained by the application, into which to retrieve the index names.


TTable::GotoCurrent

TTable	See also

Synchronizes the current record for this table with the current record of a specified table component.

void __fastcall GotoCurrent(TTable* Table);

Description

Call GotoCurrent to synchronize the cursor position for this table based on the cursor position in another dataset that uses a different data source component, but which is connected to the same underlying database table. Table is the name of the table component whose cursor position to use for synchronizing.

Note:	This procedure works only for table components that have the same DatabaseName and TableName properties. Otherwise an exception is raised.

GotoCurrent is mainly for use in applications that have two table components that are linked to the same underlying database table through different data source components. It enables an application to ensure that separate views of the data appear to be linked.


TTable::GotoKey

TTable	See also	Example

Moves the cursor to a record specified by the current key.

bool __fastcall GotoKey(void);

Description

Use GotoKey to move to a record specified by key values assigned with previous calls to SetKey or EditKey and actual search values indicated in the Fields property.

If GotoKey finds a matching record, it positions the cursor on the record and returns true. Otherwise the current cursor position remains unchanged, and GotoKey returns false.


TTable::GotoNearest

TTable	See also 	Example

Moves the cursor to the record that most closely matches the current key.

void __fastcall GotoNearest(void);

Description

Call GotoNearest to position the cursor on the record that is either the exact record specified by the current key values in the key buffer, or on the first record whose values exceed those specified.

Note:	KeyExclusive determines which records are considered part of a search range.

Before calling GotoNearest, an application must specify key values by calling SetKey or EditKey to put the dataset is dsSetKey state, and then use FieldByName to populate the key buffer property with search values.


TTable::LockTable

TTable	See also

Locks a Paradox or dBASE table.

void __fastcall LockTable(TLockType LockType);

Description

Call LockTable to lock a Paradox or dBASE table to prevent other applications from placing a particular type of lock on the table. LockType specifies the lock requested by this application.

Requesting a read lock prevents other applications from reading a table. Requesting a write lock prevents other application from writing to a table.

An application can request both types of lock by calling LockTable twice, once for each lock type.


TTable::OpenIndexFile

TTable	See also

Opens a specified dBASE non-production index file.

void __fastcall OpenIndexFile(const System::AnsiString IndexName);

Description

Call OpenIndexFile to open a specified dBASE non-production index file. IndexFileName is the name of the file to open. OpenIndexFile opens the file and adds its name to the list of index files in the IndexFiles property.

While a non-production index file is open, it is maintained.


TTable::RenameTable

TTable	See also

Renames the Paradox or dBASE table associated with this table component.

void __fastcall RenameTable(const System::AnsiString NewTableName);

Description

Call RenameTable to give a new name to the Paradox or dBASE table underlying this table component. RenameTable renames the table and any support files (for example, Paradox .DB and .MB files).


TTable::SetKey

TTable	See also 	Example

Enables setting of keys and ranges for a dataset prior to a search.

void __fastcall SetKey(void);

Description

Call SetKey to put the dataset into dsSetKey state and clear the current contents of the key buffer. The FieldByName method can be used to supply a new set of search values prior to conducting a search.

Note:	To modify an existing key or range, call EditKey.


TTable::SetRange

TTable	See also

Sets the starting and ending values of a range, and applies it.

void __fastcall SetRange(const System::TVarRec * StartValues, const int StartValues_Size, const System::TVarRec * EndValues, const int EndValues_Size);

Description

Call SetRange to specify a range and apply it to the dataset. StartValues indicates the field values that designate the first record in the range. EndValues indicates the field values that designate the last record in the range.

SetRange combines the functionality of SetRangeStart, SetRangeEnd, and ApplyRange in a single procedure call. SetRange performs the following functions:

1	Puts the dataset into dsSetKey state.

2	Erases any previously specified starting range values and ending range values.

3	Sets the start and end range values.

4	Applies the range to the dataset.

If either StartValues or EndValues has fewer elements than the number of fields in the current index, then the remaining entries are set to NULL.

Note:	With Paradox or dBASE tables, EditRangeStart works only on indexed fields. With SQL databases, EditRangeStart also works with any columns specified in the IndexFieldNames property.


TTable::SetRangeEnd

TTable	See also 	Example

Indicates that subsequent assignments to field values specify the end of the range of rows to include in the dataset.

void __fastcall SetRangeEnd(void);

Description

Call SetRangeEnd to put the dataset into dsSetKey state, erase any previous end range values, and set them to NULL. Subsequent key buffer field assignments can be made using the FieldByName method to set the ending values for a range.

After assigning end-range values to FieldValues, call ApplyRange to activate the modified range.

Note:	With Paradox or dBASE tables, SetRangeEnd works only on indexed fields. With SQL databases, SetRangeEnd also works with any columns specified in the IndexFieldNames property.


TTable::SetRangeStart

TTable	See also 	Example

Indicates that subsequent assignments to field values specify the start of the range of rows to include in the dataset.

void __fastcall SetRangeStart(void);

Description

Call SetRangeStart to put the dataset into dsSetKey state, erase any previous start range values, and set them to NULL. Subsequent field assignments to the FieldValues property indicate the actual set of starting values for a range.

After assigning start-range values to FieldValues, call ApplyRange to activate the modified range.

Note:	With Paradox or dBASE tables, SetRangeEnd works only on indexed fields. With SQL databases, SetRangeEnd also works with any columns specified in the IndexFieldNames property.


TTable::UnlockTable

TTable	See also

Removes a previously applied lock on a Paradox or dBASE table.

void __fastcall UnlockTable(TLockType LockType);

Description

Call UnlockTable to remove a lock previously applied to a Paradox or dBASE table to prevent other applications from placing a particular type of lock on the table. LockType specifies the lock to remove.

Removing a read lock enables other applications to read a table. Removing a write lock enables other application to write to a table.

An application can remove both types of lock by calling UnlockTable twice, once for each lock type.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataSet

TBDEDataSet

TDBDataSet


THTMLTableRowAttributes

Hierarchy	Properties	Methods	Events	See also

THTMLTableRowAttributes represents the display attributes of the row tag in an HTML table.

Unit

httpapp

Description

Use THTMLTableRowAttributes to describe the desired appearance of a row of an HTML table. The properties of the THTMLTableRowAttributes object correspond to the options that can be added to the HTML row tag (TR). When the attributes of all the parts of the HTML table have been specified, the content producer creates the HTML commands to specify the table as described.

THTMLTableRowAttributes introduces no new properties, events, or methods beyond those introduced by its immediate ancestor THTMLTableElementAttributes.


THTMLTableRowAttributes properties

THTMLTableRowAttributes	Alphabetically	Legend

Derived from THTMLTableElementAttributes

Align

BgColor

VAlign

Derived from THTMLTagAttributes

Custom

Producer


THTMLTableRowAttributes properties

THTMLTableRowAttributes	By object	Legend

Align

BgColor

Custom

Producer

VAlign


THTMLTableRowAttributes events

THTMLTableRowAttributes	Alphabetically

Derived from THTMLTagAttributes

OnChange


THTMLTableRowAttributes events

THTMLTableRowAttributes	By object

OnChange


THTMLTableRowAttributes methods

THTMLTableRowAttributes	Alphabetically

In THTMLTableRowAttributes

~THTMLTableRowAttributes

THTMLTableRowAttributes

Derived from THTMLTableElementAttributes

RestoreDefaults

Derived from THTMLTagAttributes

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableRowAttributes methods

THTMLTableRowAttributes	By object

~THTMLTableRowAttributes

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

THTMLTableRowAttributes


THTMLTableRowAttributes::THTMLTableRowAttributes

THTMLTableRowAttributes

Creates a new THTMLTableRowAttributes object.

__fastcall THTMLTableRowAttributes(TCustomContentProducer* Producer) : Httpapp::THTMLTableElementAttributes(Producer) { }

Description

Do not call THTMLTableRowAttributes directly. Instead, use the new keyword. Most applications do not need to create a THTMLTableRowAttributes object because it is created automatically by the content producer (usually a TDataSetTableProducer or TQueryTableProducer) that uses it.


THTMLTableRowAttributes::~THTMLTableRowAttributes

THTMLTableRowAttributes

~THTMLTableRowAttributes frees the memory associated with the THTMLTableRowAttributes object.

__fastcall virtual ~THTMLTableRowAttributes(void) { }

Description

Do not call ~THTMLTableRowAttributes directly. Instead, use the delete keyword on the object, which causes ~THTMLTableRowAttributes to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

THTMLTagAttributes

THTMLTableElementAttributes


TTabSheet

Hierarchy	Properties	Methods	Events	See also

TTabSheet is an individual page in a TPageControl object.

Unit

comctrls

Description

Use TTabSheet to represent a single page in a tabbed page control. Tab sheets are typically referred to as pages. TPageControl maintains an indexed array of its tab sheets in its Pages property. Users can click on a tab to activate the tab sheet.


TTabSheet properties

TTabSheet	Alphabetically	Legend

In TTabSheet

PageControl

PageIndex

TabIndex

TabVisible

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Font

Height

Hint

Left

Name

Parent

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TTabSheet properties

TTabSheet	By object	Legend

Align

BoundsRect

Brush

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Font

Handle

Height

HelpContext

Hint

Left

Name

Owner

PageControl

PageIndex

Parent

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ShowHint

Showing

TabIndex

TabOrder

TabStop

TabVisible

Tag

Top

VCLComObject

Visible

Width

WindowProc


TTabSheet::PageControl

TTabSheet	Example

Indicates the page control object that contains the tab sheet.

__property TPageControl* PageControl = {read=FPageControl, write=SetPageControl};

Description

Read PageControl to gain access to the page control object that uses the tab sheet. The properties and methods of the PageControl object can be used to locate the selected page, iterate through the other pages in the page control, or change the display properties of the tabs.

Set PageControl to remove the tab sheet from its current page control (if any) and insert it into a new page control.


TTabSheet::PageIndex

TTabSheet	See also	Example

Indicates the index of the tab sheet in the list of tab sheets maintained by the page control.

__property int PageIndex = {read=GetPageIndex, write=SetPageIndex, stored=false, nodefault};

Description

Use PageIndex to determine where the tab sheet sits in its page control. Each tab sheet in a page control is automatically assigned a PageIndex when it is inserted in the page control. The first tab sheet receives a value of 0, the second has a value of 1, and so on. PageIndex values are reassigned if tab sheets are deleted or moved.

To access a particular tab sheet given its index value, use the indexed Pages property of the TPageControl object.


TTabSheet::TabIndex

TTabSheet	See also

Indicates the position of the tab sheet in the set of visible tabs in a TPageControl object.

__property int TabIndex = {read=GetTabIndex, nodefault};

Description

Read TabIndex to determine where the user sees the tab sheet. A value of 0 indicates the first visible tab sheet, a value of 1 indicates the second visible tab sheet, and so on. TabIndex is always less than or equal to PageIndex. For example, a tab sheet that has a PageIndex of 3 will have a TabIndex of 2 if one of the previous tab sheets in the page control is not visible.

If a tab sheet's TabVisible property is false, the TabIndex property is -1.


TTabSheet::TabVisible

TTabSheet	See also	Example

Specifies whether the tab of the TTabSheet object appears in its TPageControl.

__property bool TabVisible = {read=FTabVisible, write=SetTabVisible, default=1};

Description

Use TabVisible to temporarily remove a tab sheet from a page control. When TabVisible is false, the tab does not appear in the page control and its TabIndex property is -1. Setting TabVisible to true allows the user to see the tab of the tab sheet again.


TTabSheet events

TTabSheet	Alphabetically	Legend

In TTabSheet

OnHide

OnShow

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnDragDrop

OnDragOver

OnMouseDown

OnMouseMove

OnMouseUp


TTabSheet events

TTabSheet	By object	Legend

OnDragDrop

OnDragOver

OnEnter

OnExit

OnHide

OnMouseDown

OnMouseMove

OnMouseUp

OnShow


TTabSheet::OnHide

TTabSheet	See also

Occurs when the TabVisible property changes to false.

__property Classes::TNotifyEvent OnHide = {read=FOnHide, write=FOnHide};

Description

Write an OnHide event handler to take specific action when the tab sheet is temporarily removed from its page control.


TTabSheet::OnShow

TTabSheet	See also

Occurs when the TabVisible property changes to true.

__property Classes::TNotifyEvent OnShow = {read=FOnShow, write=FOnShow};

Description

Write an OnShow event handler to take specific action when the tab sheet appears in its page control after being temporarily hidden.


TTabSheet methods

TTabSheet	Alphabetically

In TTabSheet

~TTabSheet

TTabSheet

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTabSheet methods

TTabSheet	By object

~TTabSheet

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TTabSheet

Update

UpdateControlState


TTabSheet::TTabSheet

TTabSheet	See also	Example

Creates and initializes an instance of TTabSheet.

__fastcall virtual TTabSheet(Classes::TComponent* AOwner);

__fastcall TTabSheet(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Call TTabSheet indirectly, using the new keyword, to instantiate a tab sheet at runtime. Tab sheets added to a page controls at design time are created automatically.

Pass a single Component as a parameter to provide the tab sheet with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the tab sheet in a non-VCL window. This syntax is used when the tab sheet is implemented as an ActiveX control that is embedded in a non-VCL window.

TTabSheet calls the parent object’s constructor method, then sets the initial values for the tab sheet component.

When creating tab sheets at runtime, use the PageControl property to insert them into a page control object.


TTabSheet::~TTabSheet

TTabSheet	See also

Destroys an instance of TTabSheet.

__fastcall virtual ~TTabSheet(void);

Description

Do not call ~TTabSheet directly at runtime. Instead, use the delete keyword. ~TTabSheet removes the tab sheet from the page control and then calls the parent object’s destructor method.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


THTMLTableColumn

Hierarchy	Properties	Methods	See also

THTMLTableColumn represents the display attributes and field binding of a column in the HTML representation of a dataset.

Unit

dbweb

Description

Use THTMLTableColumn to specify the appearance or value of a column in a table produced by TDSTableProducer. Applications can set the properties of the columns programmatically at runtime, or use the Columns editor at design time.


THTMLTableColumn properties

THTMLTableColumn	Alphabetically	Legend

In THTMLTableColumn

Align

BgColor

Custom

DisplayName

Field

FieldName

Title

VAlign

Derived from TCollectionItem

Collection

ID

Index


THTMLTableColumn properties

THTMLTableColumn	By object	Legend

Align

BgColor

Collection

Custom

DisplayName

Field

FieldName

ID

Index

Title

VAlign


THTMLTableColumn::Align

THTMLTableColumn	See also

Specifies the horizontal alignment of the contents of the cells in the column.

enum THTMLAlign { haDefault, haLeft, haRight, haCenter };

__property Httpapp::THTMLAlign Align = {read=FAlign, write=SetAlign, default=0};

Description

Set Align to indicate the desired horizontal alignment of text in the cells of the column. Align indicates the desired value of the Align option of the HTML TD tag.

The default value of Align is haDefault, which means the web browser that reads the HTML document horizontally positions the contents of cells wherever it wishes. Align can take any of the following values:

Value	Meaning

haDefault	The web browser can position the contents of cells anywhere horizontally.

haLeft	Web browsers position the contents of cells in the column so that they appear lined up on the left.

haRight	Web browsers position the contents of cells in the column so that they appear lined up on the right.

haCenter	Web browsers horizontally center the contents of the cells in the column.


THTMLTableColumn::BgColor

THTMLTableColumn	See also 	Example

Specifies the background color of the cells in the column.

__property System::AnsiString BgColor = {read=FBgColor, write=SetBgColor};

Description

Use BgColor to indicate a value for the BgColor option of the HTML TD tag. The value of BgColor is the name of color. This can be one of the following strings:

Aqua	Black	Blue
Fuschia	Gray	Green
Lime	Maroon	Navy
Olive	Purple	Red
Silver	Teal	White
Yellow
Use the BgColor property of the THTMLTableAttributes object to set a background color for the entire table. Use the BgColor property of THTMLTableColumn to make a column stand out from the rest of the table.


THTMLTableColumn::Custom

THTMLTableColumn	See also

Specifies a tag option and its value in the HTML TD tags for the cells in the column.

__property System::AnsiString Custom = {read=FCustom, write=SetCustom};

Description

Use Custom to represent one or more options to be added to an HTML tag. Each option and its value should have the form

OPTIONNAME=Value

If Custom specifies more than one option, each object should be separated from the others by spaces.


THTMLTableColumn::DisplayName

THTMLTableColumn	See also

Names an individual HTML table column within a collection of columns.

__property System::AnsiString DisplayName = {read=GetDisplayName, write=SetDisplayName};

Description

Use DisplayName to name a particular column in the list of columns maintained by TDSTableProducer. DisplayName is also the string that appears in the header cell at the top of the column.

Note:	If the FieldName property is set, reading DisplayName will always return FieldName, even if DisplayName was set to another value.


THTMLTableColumn::Field

THTMLTableColumn	See also

Indicates the field component associated with the field binding of the column.

__property Db::TField* Field = {read=GetField, write=SetField};

Description

Read Field to get direct access to the field component for the column. Usually, Field is a field component maintained by the dataset. In some cases, however, Field is maintained directly by THTMLTableColumn, such as when the column represents a calculated field. Do not set the Field property unless the TField object is obtained from the dataset of the TDSTableProducer that uses this THTMLTableColumn object, or is a calculated field based on that dataset.

Setting Field automatically updates the FieldName property.


THTMLTableColumn::FieldName

THTMLTableColumn	See also

Specifies the name of the field to which the column is bound.

__property System::AnsiString FieldName = {read=FFieldName, write=SetFieldName};

Description

Set FieldName to specify the field binding for the column in the HTML table. FieldName identifies a particular field component in the dataset of the TDSTableProducer object that uses this THTMLTableColumn object.

Setting Fieldname automatically updates the Field property.


THTMLTableColumn::Title

THTMLTableColumn	See also

Specifies the display attributes to be added to the header cell that appears at the top of the column.

__property Httpapp::THTMLTableHeaderAttributes* Title = {read=FTitle, write=SetTitle};

Description

Set Title to a THTMLTableHeaderAttributes object that describes the display attributes for the HTML TH tag for the header cell at the top of the column. Setting Title calls the Assign method of the THTMLTableHeaderAttributes object stored internally by THTMLTableColumn. Thus, the memory for any table header attributes object assigned to the Title property is never owned or freed by the HTML table column.

Note:	Not all the properties of the table header attributes object are copied when one table attributes object is assigned to another. To ensure that all the attributes represented by Title are set appropriately, read Title and set the individual properties of the THTMLTableHeaderAttributes object.


THTMLTableColumn::VAlign

THTMLTableColumn	See also

Specifies the vertical alignment of the contents of the cells in the column.

enum THTMLVAlign { haVDefault, haTop, haMiddle, haBottom, haBaseline };

__property Httpapp::THTMLVAlign VAlign = {read=FVAlign, write=SetVAlign, default=0};

Description

Set VAlign to indicate the desired vertical alignment of text in the cells of the column. VAlign indicates the desired value of the Align option of the HTML TD tag.

The default value of VAlign is haVDefault, which means the web browser that reads the HTML document vertically positions the contents of cells wherever it wishes. VAlign can take any of the following values:

Value	Meaning

haVDefault	The Web browser can position the contents of cells anywhere vertically.

haTop	Web browsers position the contents of cells in the column so that they appear lined up on the top.

haMiddle	Web browsers vertically center the contents of cells in the column.

haBottom	Web browsers position the contents of cells in the column so that they appear lined up on the bottom.


THTMLTableColumn methods

THTMLTableColumn	Alphabetically

In THTMLTableColumn

~THTMLTableColumn

AssignTo

RestoreDefaults

THTMLTableColumn

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableColumn methods

THTMLTableColumn	By object

~THTMLTableColumn

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

THTMLTableColumn


THTMLTableColumn::AssignTo

THTMLTableColumn	See also

Copies the properties of a THTMLTableColumn object to another THTMLTableColumn object.

virtual void __fastcall AssignTo(Classes::TPersistent* Dest);

Description

Applications can not call the protected AssignTo method. To assign the properties of a THTMLTableColumn object to another object, use the Assign method of the destination object.

When the Assign method of another object specifies a THTMLTableColumn object as the source of the assignment, the AssignTo method of the THTMLTableColumn object is called. AssignTo checks whether the Dest parameter is another THTMLTableColumn object, and if so, copies the values of all properties except Custom and DisplayName. If Dest is any other class of object, the inherited method is called.


THTMLTableColumn::THTMLTableColumn

THTMLTableColumn	See also

Creates an instance of THTMLTableColumn.

__fastcall virtual THTMLTableColumn(Classes::TCollection* Collection);

Description

Do not call THTMLTableColumn to create and initialize a THTMLTableColumn object. Columns created using the Columns editor at design time are created automatically. At runtime, create THTMLTableColumn objects using the Add or Insert methods of the THTMLTableColumns object that manages them.

After allocating the THTMLTableColumn object, THTMLTableColumn tells the associated TDSTableProducer object to update its layout.


THTMLTableColumn::~THTMLTableColumn

THTMLTableColumn	See also

Destroys an instance of THTMLTableColumn.

__fastcall virtual ~THTMLTableColumn(void);

Description

Do not call ~THTMLTableColumn. THTMLTableColumns frees the individual column objects it manages.


THTMLTableColumn::RestoreDefaults

THTMLTableColumn	See also

Changes all properties of the attributes object back to their initial settings.

void __fastcall RestoreDefaults(void);

Description

Call RestoreDefaults to undo any changes that were made to the table element attributes either programmatically, or using the Columns editor at design time. RestoreAttributes sets

•	Align to haDefault, and VAlign to haVDefault.

•	BgColor to an empty string.

•	Custom to an empty string.

It also restores the default settings for the THTMLTableHeaderAttributes object that represents the title of the column.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollectionItem


THTMLTableColumns

Hierarchy	Properties	Methods	See also

THTMLTableColumns is a collection of THTMLTableColumn objects that describe the display attributes and field bindings of the columns in an HTML representation of tabular data.

Unit

dbweb

Description

THTMLTableColumns is tailored for use by TDSTableProducer. It stores and manages changes to the THTMLTableColumn objects that describe the columns of the HTML table produced by TDSTableProducer. THTMLTableColumns informs the table producer of changes to the column bindings so the table producer can recompute its layout.


THTMLTableColumns properties

THTMLTableColumns	Alphabetically	Legend

In THTMLTableColumns

DSTableProducer

Items

State

Derived from TCollection

Count

ItemClass


THTMLTableColumns properties

THTMLTableColumns	By object	Legend

Count

DSTableProducer

ItemClass

Items

State


THTMLTableColumns::DSTableProducer

THTMLTableColumns	See also

Indicates the table producer that uses THTMLTableColumns to store and manage column descriptions.

__property TDSTableProducer* DSTableProducer = {read=FDSTableProducer};

Description

Read DSTableProducer to gain direct access to the table producer that uses the THTMLTableColumns object. THTMLTableColumns uses this property to inform the table producer of changes to the columns so that it can recompute its layout.


THTMLTableColumns::Items

THTMLTableColumns	See also 	Example

Lists the THTMLTableColumn objects that THTMLTableColumns stores and manages for its TDSTableProducer object.

__property THTMLTableColumn* Items[int Index] = {read=GetColumn, write=SetColumn};

Description

Use Items to access the individual column descriptors managed by THTMLTableColumns. Items is an indexed array, where the first column descriptor has index 0, the second column descriptor has index 1, and so on.


THTMLTableColumns::State

THTMLTableColumns	See also

Indicates whether the individual column descriptors are generated dynamically or statically stored.

enum THTMLColumnState { csDefault, csCustom };

__property THTMLColumnState State = {read=GetState, write=SetState, nodefault};

Description

Set State to csDefault to indicate that the column descriptors should be generated dynamically. Dynamically generated column descriptors impose no special display attributes on the columns of the HTML table, and correspond exactly in order and number to the fields of the dataset. Setting State to csDefault replaces all the column descriptors in the collection with dynamically generated defaults.

Set State to csCustom before customizing the column descriptors by adding display attributes, reordering the fields, adding columns for calculated fields, or including only a subset of the fields in the dataset. When State is csCustom, the column descriptors are saved with the TDSTableProducer object.

Note:	Using the Columns editor to customize the column descriptors automatically sets State to csCustom.


THTMLTableColumns methods

THTMLTableColumns	Alphabetically

In THTMLTableColumns

~THTMLTableColumns

Add

RebuildColumns

RestoreDefaults

THTMLTableColumns

Derived from TCollection

Assign

BeginUpdate

Clear

EndUpdate

FindItemID

Insert

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTableColumns methods

THTMLTableColumns	By object

~THTMLTableColumns

Add

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

EndUpdate

FieldAddress

FindItemID

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

Insert

InstanceSize

MethodAddress

MethodName

NewInstance

RebuildColumns

RestoreDefaults

SafeCallException

THTMLTableColumns


THTMLTableColumns.Add

THTMLTableColumns	See also

Adds a new column descriptor to the end of the Items array.

HIDESBASE THTMLTableColumn* __fastcall Add(void);

Description

Call Add to add a column descriptor to the collection of columns shown in the HTML table generated by TDSTableProducer. Applications should only call Add when the value of the State property is csCustom.


THTMLTableColumns::THTMLTableColumns

THTMLTableColumns	See also

Creates an instance of THTMLTableColumns.

__fastcall THTMLTableColumns(TDSTableProducer* DSTableProducer, System::TMetaClass* ColumnClass);

Description

Do not call the constructor of THTMLTableColumns. TDSTableProducer calls THTMLTableColumns from its own constructor. The DSTableProducer parameter specifies the TDSTableProducer object which uses the THTMLTableColumns object to manage its column descriptors. The ColumnClass parameter indicates the class of the THTMLTableColumn objects that fill the Items array.


THTMLTableColumns::RebuildColumns

THTMLTableColumns	See also

Replaces all the column descriptors in the Items array with new column descriptors that exactly match the fields in the dataset of DSTableProducer.

void __fastcall RebuildColumns(void);

Description

Call RebuildColumns to set the collection of column descriptors to the default state which matches the order and number of fields in the dataset, and which imposes no special display attributes. RebuildColumns returns the collection of column descriptors to the state that is dynamically maintained when the State property is csDefault.


THTMLTableColumns::RestoreDefaults

THTMLTableColumns	See also

Restores the default properties of every column in the Items property array.

void __fastcall RestoreDefaults(void);

Description

At design time, RestoreDefaults is called when the Restore defaults button is pressed in the Response editor.


THTMLTableColumns::~THTMLTableColumns

THTMLTableColumns

Frees the memory associated with the THTMLTableColumns object.

__fastcall virtual ~THTMLTableColumns(void) { }

Description

Do not call ~THTMLTableColumns directly. Instead, use the delete keyword on the object, which causes ~THTMLTableColumns to be invoked automatically.


Accessibility

Read-only


Hierarchy

TObject

TPersistent

TCollection


THTMLTagAttributes

Hierarchy	Properties	Methods	Events	See also

THTMLTagAttributes is the base class for all objects that represent the attributes of an HTML tag.

Unit

httpapp

Description

Descendants of TCustomContentProducer use THTMLTagAttributes objects to encapsulate the options added to the HTML tags in the HTML commands that they produce. When the TCustomContentProducer object generates HTML commands, it looks up the tag attributes represented by the properties of its tag attributes objects, and generates the appropriate tag options.


THTMLTagAttributes properties

THTMLTagAttributes	Alphabetically	Legend

In THTMLTagAttributes

Custom

Producer


THTMLTagAttributes properties

THTMLTagAttributes	By object	Legend

Custom

Producer


THTMLTagAttributes::Custom

THTMLTagAttributes	See also

Represents a tag option and its value in an HTML tag.

__property System::AnsiString Custom = {read=FCustom, write=SetCustom};

Description

Use Custom to represent one or more options to be added to an HTML tag. Each option and its value should have the form

OPTIONNAME=Value

The options specified by Custom should be separated by spaces. For example, to merge a cell in an HTML table with the three adjacent cells to the left and below, the table data tag for the cell requires the ROWSPAN and COLSPAN options to be set. The value of Custom to specify these values would be the string

ROWSPAN=2 COLSPAN=2

The HTML producer should insert the Custom string into the HTML tag when it generates its Content.


THTMLTagAttributes::Producer

THTMLTagAttributes	See also

Indicates the content producer that uses the THTMLTagAttributes object to represent the options for one of the HTML tags in the content it produces.

__property TCustomContentProducer* Producer = {read=FProducer};

Description

Use Producer to gain access to the HTML producer object that is using the THTMLTagAttributes object. The THTMLTagAttributes object can use the Producer property in an OnChange event handler to notify the TCustomContentProducer object of changes to the attributes it represents.


THTMLTagAttributes events

THTMLTagAttributes	Alphabetically

In THTMLTagAttributes

OnChange


THTMLTagAttributes events

THTMLTagAttributes	By object

OnChange


THTMLTagAttributes::OnChange

THTMLTagAttributes	See also

Occurs immediately after a tag attributes property changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action whenever any of the properties of the tag attributes object changes. When OnChange occurs, the tag attributes object already has the new property setting. Use an OnChange event handler to inform the HTML content producer whenever the attributes of a tag change if the content producer needs to update the content it is producing.


THTMLTagAttributes methods

THTMLTagAttributes	Alphabetically	Legend

In THTMLTagAttributes

~THTMLTagAttributes

Changed

RestoreDefaults

THTMLTagAttributes

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


THTMLTagAttributes methods

THTMLTagAttributes	By object	Legend

~THTMLTagAttributes

Assign

Changed

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RestoreDefaults

SafeCallException

THTMLTagAttributes


THTMLTagAttributes::Changed

THTMLTagAttributes	See also

Generates an OnChange event.

void __fastcall Changed(void);

Description

Call Changed from a descendant of THTMLTagAttributes after a tag option introduced by that descendant changes. Changed is exposed as a protected method so that component writers can create descendants of THTMLTagAttributes which correctly trigger the OnChange event handler.


THTMLTagAttributes::THTMLTagAttributes

THTMLTagAttributes	See also

Creates an instance of THTMLTagAttributes.

__fastcall THTMLTagAttributes(TCustomContentProducer* Producer);

Description

Do not call THTMLTagAttributes directly. To create and initialize an instance of THTMLTagAttributes at runtime, use the new keyword. After calling the parent class’s constructor, THTMLTagAttributes sets the Producer property to the value of the Producer parameter.


THTMLTagAttributes::RestoreDefaults

THTMLTagAttributes	See also

Changes all properties of the tag attributes object back to their initial settings.

virtual void __fastcall RestoreDefaults(void);

Description

Call RestoreDefaults to undo any changes that were made to the tag attributes either programmatically, or at design time. RestoreAttributes sets the Custom property to an empty string.


THTMLTagAttributes::~THTMLTagAttributes

THTMLTagAttributes

Frees the memory associated with the THTMLTagAttributes object.

__fastcall virtual ~THTMLTagAttributes(void) { }

Description

Do not call ~THTMLTagAttributes directly. Instead, use the delete keyword on the object, which causes ~THTMLTagAttributes to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject

TPersistent


TTextAttributes

Hierarchy	Properties	Methods	See also 	Example

TTextAttributes represents the font characteristics of a section of text in a rich edit control.

Unit

comctrls

Description

TTextAttributes includes a number of properties that describe the font characteristics of some text in a rich text document. TTextAttributes is tailored to allow a descendant of TCustomRichEdit to read and write the default text characteristics (via its DefAttributes property) or the characteristics of the selected text (via its SelAttributes property). The properties of a TTextAttributes object are invalid unless it is owned by a descendant of TCustomRichEdit.

Most of the font characteristics represented by a TTextAttributes object are the same as the properties of a TFont object with the same names. Applications can assign fonts to text attributes and vice versa.


TTextAttributes properties

TTextAttributes	Alphabetically	Legend

In TTextAttributes

CharSet

Color

ConsistentAttributes

Height

Name

Pitch

Protected

Size

Style


TTextAttributes properties

TTextAttributes	By object	Legend

CharSet

Color

ConsistentAttributes

Height

Name

Pitch

Protected

Size

Style


TTextAttributes::CharSet

TTextAttributes	See also

Specifies the character set of the font.

typedef Byte TFontCharset;

__property Graphics::TFontCharset Charset = {read=GetCharset, write=SetCharset, nodefault};

Description

Set Charset to identify the character set of the font. Each typeface (specified by the Name property) supports one or more character sets. Check the information supplied by the font vendor to determine what values of Charset are valid.

The following table lists the predefined constants provided for standard character sets:

Constant	Value	Description

ANSI_CHARSET	0	ANSI characters.

DEFAULT_CHARSET	1	Font is chosen based solely on Name and Size. If the described font is not available on the system, Windows will substitute another font.

SYMBOL_CHARSET	2	Standard symbol set.

MAC_CHARSET	77	Macintosh characters. Not available on NT 3::51.

SHIFTJIS_CHARSET	128	Japanese shift-jis characters.

HANGEUL_CHARSET	129	Korean characters (Wansung).

JOHAB_CHARSET	130	Korean characters (Johab). Not available on NT 3::51

GB2312_CHARSET	134	Simplified Chinese characters (mainland china).

CHINESEBIG5_CHARSET	136	Traditional Chinese characters (taiwanese).

GREEK_CHARSET	161	Greek characters. Not available on NT 3::51.

TURKISH_CHARSET	162	Turkish characters. Not available on NT 3::51

VIETNAMESE_CHARSET	163	Vietnamese characters. Not available on NT 3::51.

HEBREW_CHARSET	177	Hebrew characters. Not available on NT 3::51

ARABIC_CHARSET	178	Arabic characters. Not available on NT 3::51

BALTIC_CHARSET	186	Baltic characters. Not available on NT 3::51.

RUSSIAN_CHARSET	204	Cyrillic characters. Not available on NT 3::51.

THAI_CHARSET	222	Thai characters. Not available on NT 3::51

EASTEUROPE_CHARSET	238	Includes diacritical marks for eastern european countries. Not available on NT 3::51.

OEM_CHARSET	255	Depends on the codepage of the operating system.


TTextAttributes::Color

TTextAttributes	See also	Example

Indicates the foreground color of the text.

__property Graphics::TColor Color = {read=GetColor, write=SetColor, nodefault};

Description

Use color to indicate the color of the actual characters. the background color is a property of the rich edit control that uses the TTextAttributes object, and should be set by the Color property of the rich edit control.


TTextAttributes::ConsistentAttributes

TTextAttributes	See also

Indicates which of the properties of the TTextAttributes object are consistent throughout the text of the current selection in the rich edit object.

enum TConsistentAttribute { caBold, caColor, caFace, caItalic, caSize, caStrikeOut, caUnderline, caProtected };

typedef Set<TConsistentAttribute, caBold, caProtected> TConsistentAttributes;

__property TConsistentAttributes ConsistentAttributes = {read=GetConsistentAttributes, nodefault};

Description

Read the ConsistentAttributes of the SelAttributes property of a rich text object to discover which of the properties of the TTextAttributes are meaningful for the current selection. This information is relevant if you want to then read the text characteristics of the current selection. Setting a property of TTextAttributes will cause that property to become a consistent attribute until the selection changes.

ConsistentAttributes is a set drawn from the following values:

Value	Meaning

caBold	Characters are consistently either bold or not bold throughout the selection.

caColor	The color of character font is consistent throughout the selection.

caFace	The typeface of the character font is consistent throughout the selection.

caItalic	Characters are consistently either italic or not italic throughout the selection.

caSize	The size of the character font is consistent throughout the selection.

caStrikeout	Characters consistently either have the strikeout style or they do not have the strikeout style throughout the selection.

caUnderline	Characters are consistently either underlined or not underlined throughout the selection.

caProtected	Text is consistently either protected or not protected.

Note:	Use ConsistentAttributes with the SelAttributes property of the rich edit control. The ConsistentAttributes of the DefAttributes property of the rich edit control is the empty set, even though all attributes are consistent in the section of text that has the default attributes.


TTextAttributes::Height

TTextAttributes	See also	Example

Specifies the height of the font in pixels.

__property int Height = {read=GetHeight, write=SetHeight, nodefault};

Description

To specify a font height in pixels, use the Height property. To specify the size of the font in points instead, use the Size property. Users usually specify font size in points within an application, while programmers are often concerned with the actual size of the font in pixels when displaying a font on the screen.

The relationship between the Height and Size properties is expressed by the formula:

Height = Size * ScreenPixelsPerInch / 72

Note:	Unlike the Height property of a TFont object, the Height property of a TTextAttributes object always includes the internal leading that appears at the top of the font.


TTextAttributes::Name

TTextAttributes	See also

Specifies the typeface of the font described by the TTextAttributes object.

__property System::AnsiString Name = {read=GetName, write=SetName};

Description

Use Name to specify the typeface of the font. Typefaces are strings of up to 32 characters used by Windows to identify a font. The Name is the identifier for the font that most font selection controls show.


TTextAttributes::Pitch

TTextAttributes	See also

Specifies whether the characters in the font all have the same width.

enum TFontPitch { fpDefault, fpVariable, fpFixed };

__property Graphics::TFontPitch Pitch = {read=GetPitch, write=SetPitch, nodefault};

Description

Each typeface has an associated pitch. The characters in fixed-pitch fonts are all the same width. The characters in variable-pitch fonts differ in width. Fixed pitch fonts are generally used for representing source code, because they allow the indentation to line up properly. Variable pitch fonts are generally used to give text a more natural appearance.

Here are the possible values for Pitch:

Value	Meaning

fpDefault	The font pitch is set to the default value, which depends on the font specified in the Name property.

fpFixed	The font pitch is set to fixed. All characters in the font have the same width.

fpVariable	The font pitch is set to variable. The characters in the font have different widths.

Note:	Setting the Pitch of a fixed-pitch font to fpVariable or a variable-pitch font to fpFixed will cause Windows to find what it considers the best match to all of the font characteristics that have been specified. This might have no effect on the appearance of a font, or might cause Windows to substitute a different font with the appropriate pitch. For example, setting the pitch of MS Serif (a variable-pitch font) to fpFixed causes Courier to be displayed.


TTextAttributes::Protected

TTextAttributes	See also

Indicates whether the text represented by the TTextAttributes object is protected.

__property bool Protected = {read=GetProtected, write=SetProtected, nodefault};

Description

Protected text can’t be changed by the user. When the user attempts to edit a selection that includes protected text, the rich edit control calls the OnProtectChange event handler. The OnProtectChange event handler can then permit or disallow the editing of the protected text. If there is no OnProtectChange event handler, protected text is read-only.


TTextAttributes::Size

TTextAttributes	See also

Specifies the height of the font in points.

__property int Size = {read=GetSize, write=SetSize, nodefault};

Description

To specify a font height in points, use the Size property. To specify the size of the font in pixels instead, use the Height property. Users usually specify font size in points within an application, while programmers are usually concerned with the actual size of the font in pixels when displaying a font on the screen.

The relationship between the Height and Size properties is expressed by the formula:

Size = Height * 72 / ScreenPixelsPerInch

Note:	Unlike the Size property of a TFont object, the Size property of a TTextAttributes object always omits the internal leading that appears at the top of the font.


TTextAttributes::Style

TTextAttributes	See also	Example

Determines whether the font is normal, italic, underlined, bold, or strikeout.

enum TFontStyle { fsBold, fsItalic, fsUnderline, fsStrikeOut };

typedef Set<TFontStyle, fsBold, fsStrikeOut>  TFontStyles;

__property Graphics::TFontStyles Style = {read=GetStyle, write=SetStyle, nodefault};

Description

The Style property is a set drawn from the following values:

Value	Meaning

fsBold	The font is boldfaced.

fsItalic	The font is italicized.

fsUnderline	The font is underlined.

fsStrikeout	The font is displayed with a horizontal line through it.

Because the Style property is a set, it can contain multiple values. For example, a font could be both boldfaced and italicized.


TTextAttributes methods

TTextAttributes	Alphabetically	Legend

In TTextAttributes

~TTextAttributes

Assign

AssignTo

InitFormat

TTextAttributes

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TTextAttributes methods

TTextAttributes	By object	Legend

~TTextAttributes

Assign

AssignTo

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

InheritsFrom

InitFormat

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TTextAttributes


TTextAttributes::Assign

TTextAttributes	See also 	Example

Sets the properties of a TTextAttributes object to match the properties specified in another TTextAttributes object or in a TFont object.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to change all the text attributes at once. Assign can set the font characteristics of the selected text to match the default font characteristics or vice versa. When the Source is a TTextAttributes object, Assign matches only the Color, Name, Style, and Pitch properties. When the Source is a TFont object, Assign matches the Size as well.

Note:	Assign only succeeds at runtime when the Source is a TTextAttributes object, a TFont object, or an object that has implemented an AssignTo method that deals with the TTextAttributes object. Other source objects will throw an EConvertError exception.


TTextAttributes::AssignTo

TTextAttributes	See also

Enables the properties of a TTextAttributes object to be assigned to a TFont object.

virtual void __fastcall AssignTo(Classes::TPersistent* Dest);

Description

TTextAttributes overrides the parent class’s AssignTo method to enable its font properties to be assigned to a TFont object. Applications should not call AssignTo. It is called when the Assign method of the TFont object is called. AssignTo copies the CharSet, Color, Name, Style, Size, and Pitch properties to the TFont object.


TTextAttributes::TTextAttributes

TTextAttributes	See also

Creates an instance of TTextAttributes.

enum TAttributeType { atSelected, atDefaultText };

__fastcall TTextAttributes(TCustomRichEdit* AOwner, TAttributeType AttributeType);

Description

Do not call the constructor for TTextAttributes. TTextAttributes objects are created from the constructor of the rich edit control. The rich edit control uses an attribute type of atDefaultText to implement its DefAttributes property, and an attribute type of atSelected to implement its SelAttributes property.


TTextAttributes::InitFormat

TTextAttributes	See also

Initializes a Windows TCharFormat structure.

void __fastcall InitFormat(Richedit::TCharFormatA &Format);

Description

TTextAttributes uses the TCharFormat structure to communicate with the rich edit control window when it gets and sets properties. InitFormat initializes this structure before any particular properties are read or set. InitFormat is exposed as a protected method so that derived classes can use the TCharFormat structure in the implementation of any other text properties.


Accessibility

Read-only


TTextAttributes::~TTextAttributes

TTextAttributes

Frees the memory associated with the TTextAttributes object.

__fastcall virtual ~TTextAttributes(void) { }

Description

Do not call ~TTextAttributes directly. Instead, use the delete keyword on the object, which causes ~TTextAttributes to be invoked automatically.


Scope

Protected


Hierarchy

TObject

TPersistent


TThreadList

Hierarchy	Methods	See also

TThreadList represents a thread-safe list.

Unit

classes

Description

A TThreadList object is a thread-safe list. Each TThreadList maintains a private TList (a list of pointers to objects). You can add or remove items in a TThreadList from multiple threads without explicit locks.

To access the actual TList object managed by the thread list, first lock the list by calling the LockList method.  Unlock the list by calling the Unlock method when done.


TThreadList methods

TThreadList	Alphabetically

In TThreadList

~TThreadList

Add

Clear

LockList

Remove

TThreadList

UnlockList

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TThreadList methods

TThreadList	By object

~TThreadList

Add

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

LockList

MethodAddress

MethodName

NewInstance

Remove

SafeCallException

TThreadList

UnlockList


TThreadList.Add

TThreadList

Adds an item to the list.

void __fastcall Add(void * Item);

Description

Call Add to insert a new object at the end of the thread-safe list.


TThreadList::Clear

TThreadList	See also

Deletes all items from the list.

void __fastcall Clear(void);

Description

Clear locks the list, calls the Clear method in TList, then unlocks the list.


TThreadList::TThreadList

TThreadList

Creates and initializes a TThreadList instance.

__fastcall TThreadList(void);

Description

Use the new keyword when creating a new TThreadList instance.


TThreadList::~TThreadList

TThreadList	See also

Destroys the TThreadList and frees its memory.

__fastcall virtual ~TThreadList(void);

Description

Do not call ~TThreadList directly in an application. Instead, use the delete keyword.


TThreadList::LockList

TThreadList	See also 	Example

Locks the thread-safe list and returns a TList object.

TList* __fastcall LockList(void);

Description

LockList calls the Windows EnterCriticalSection function to lock the thread-safe list. It then returns the TList object that contains the list.


TThreadList::Remove

TThreadList	See also

Removes an item from the list.

void __fastcall Remove(void * Item);

Description

Call Remove to remove a specific item from the list without having to determine its index. Remove locks the list, calls the Remove method in TList, then unlocks the list.


TThreadList::UnlockList

TThreadList	See also 	Example

Unlocks the thread-safe list.

void __fastcall UnlockList(void);

Description

UnlockList calls the Windows LeaveCriticalSection function. Use UnlockList after LockList to relock the list.


Hierarchy

TObject


TThread

Hierarchy	Properties	Methods	Events	See also

TThread is an abstract class that enables creation of separate threads of execution in an application.

Unit

classes

Description

Create a descendant of TThread to represent an execution thread in a multi-threaded application.  Each new instance of a subclassed TThread object is a new thread of execution. Multiple instances of a TThread derived class make a C++Builder application multi-threaded.

When an application is run, it is loaded into memory ready for execution. At this point it becomes a process containing one or more threads that contain the data, code and other system resources for the program. A thread executes one part of an application and is allocated CPU time by the operating system. All threads of a process share the same address space and can access the process’s global variables.

Use threads to improve application performance by

•	Managing input from several communication devices.

•	Distinguishing among tasks of varying priority.  For example, a high priority thread handles time critical tasks, and a low priority thread performs other tasks.

Following are issues and recommendations to be aware of when using threads:

•	Keeping track of too many threads consumes CPU time; the recommended limit is 16 threads per process on single processor systems.

•	With multiple threads updating the same resources, keep threads synchronized to avoid conflicts.

•	Most methods that access a VCL object and update a form must only be called from within the main VCL thread.

To create and use a new thread object:

•	Choose File | New | Thread Object to create a new unit that contains an object derived from the TThread class.

•	Define the new thread object’s constructor.

•	Define the thread object’s Execute method by inserting the code that should execute when the thread is executed.

•	Pass any calls that use a VCL component to the Synchronize method which causes the main VCL thread to execute the call, avoiding multi-thread conflicts.

Note:	See C++BUILDER 3::0/DEMOS/THREADS for multi-threading program samples.


TThread properties

TThread	Alphabetically	Legend

In TThread

FreeOnTerminate

Handle

Priority

ReturnValue

Suspended

Terminated

ThreadID


TThread properties

TThread	By object	Legend

FreeOnTerminate

Handle

Priority

ReturnValue

Suspended

Terminated

ThreadID


TThread::FreeOnTerminate

TThread	See also

Determines whether the thread object is automatically destroyed when the thread terminates.

__property bool FreeOnTerminate = {read=FFreeOnTerminate, write=FFreeOnTerminate, nodefault};

Description

FreeOnTerminate is false by default. If the default is used, the thread object must be explicitly destroyed in the application code.


TThread::Handle

TThread	See also

Contains the thread's handle.

__property int Handle = {read=FHandle, nodefault};

Description

Use Handle when calling Win32 API functions for thread manipulation.


TThread::Priority

TThread	See also 	Example

Determines the thread's scheduling priority relative to other threads in the process.

__property TThreadPriority Priority = {read=GetPriority, write=SetPriority, nodefault};

Description

The Priority property is an enumerated type whose default is tpNormal; adjust the priority higher or lower as needed.

TThreadPriority type defines the possible values for the Priority property of the TThread component, as defined in the following table. Windows schedules CPU cycles to each thread based on a priority scale; the Priority property adjusts a thread's priority higher or lower on the scale.

Values	Meaning

tpIdle	The thread executes only when the system is idle-Windows won't interrupt other threads to execute a thread with tpIdle priority.

tpLowest	The thread's priority is two points below normal.

tpLower	The thread's priority is one point below normal.

tpNormal	The thread has normal priority.

tpHigher	The thread's priority is one point above normal.

tpHighest	The thread's priority is two points above normal.

tpTimeCritical	The thread gets highest priority.

Warning:	Boosting the thread priority of a CPU intensive operation may “starve” the other threads in the application. Only apply priority boosts to threads that spend most of their time waiting for external events.


TThread::ReturnValue

TThread	See also

Specifies a value returned to other waiting threads when the thread finishes executing.

__property int ReturnValue = {read=FReturnValue, write=FReturnValue, nodefault};

Description

Use ReturnValue to indicate success/failure or numeric result/output of the thread to the application or other threads. The WaitFor method returns the value stored in ReturnValue.


TThread::Suspended

TThread	See also

Indicates whether a thread is suspended.

__property bool Suspended = {read=FSuspended, write=SetSuspended, nodefault};

Description

Suspended threads don't continue execution until they're resumed. Set Suspended to true to suspend a thread; set it to false to resume it.


TThread::Terminated

TThread	See also 	Example

Indicates that the thread has been asked to terminate. The Terminate method sets the Terminated property to true.

__property bool Terminated = {read=FTerminated, nodefault};

Description

The thread's Execute method and any methods that Execute calls should check Terminated periodically and exit when it's true.

The Terminate method is the polite way to abort the execution of a thread, but it requires cooperation from the thread’s Execute code. Using terminate is recommended over the TerminateThread Win32 API call.


TThread::ThreadID

TThread	See also

Identifies the thread throughout the system.

__property int ThreadID = {read=FThreadID, nodefault};

Description

ThreadID is useful when calling Win32 API functions for manipulating the thread.

Note:	ThreadID is different than the thread’s handle in the Handle property.


TThread events

TThread	Alphabetically

In TThread

OnTerminate


TThread events

TThread	By object

OnTerminate


TThread::OnTerminate

TThread	See also

Occurs after the thread's Execute method has returned and before the thread is destroyed.

__property TNotifyEvent OnTerminate = {read=FOnTerminate, write=FOnTerminate};

Description

The OnTerminate event handler is called in the context of the main VCL thread, which means VCL methods and properties can be called freely. The thread object may also be freed within the event handler.


TThread methods

TThread	Alphabetically	Legend

In TThread

~TThread

DoTerminate

Execute

Resume

Suspend

Synchronize

Terminate

TThread

WaitFor

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TThread methods

TThread	By object	Legend

~TThread

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

DoTerminate

Execute

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Resume

SafeCallException

Suspend

Synchronize

Terminate

TThread

WaitFor


TThread::TThread

TThread	See also 	Example

Creates an instance of a thread object.

__fastcall TThread(bool CreateSuspended);

Description

Do not use TThread directly to create a thread in an application. Instead, use the new keyword, passing in the CreateSuspended argument. If CreateSuspended is false, Execute is called immediately. If CreateSuspended is true, Execute won’t be called until after Resume is called.


TThread::~TThread

TThread	See also

Destroys the thread object and releases the memory allocated to it.

__fastcall virtual ~TThread(void);

Description

Do not call ~TThread in an application. Instead, use the delete keyword to destroy a thread when FreeOnTerminate is false.

 ~TThread signals the thread to terminate and then waits for the thread to return before calling the parent class’s destructor.


TThread::DoTerminate

TThread	See also

Generates an OnTerminate event.

virtual void __fastcall DoTerminate(void);

Description

DoTerminate calls the OnTerminate event handler, but does not terminate the thread.


TThread::Execute

TThread	See also 	Example

Provides a pure virtual method to contain the code which executes when the thread is run.

virtual void __fastcall Execute(void) = 0;

Description

Overide Execute and insert the code that should be executed when the thread runs. Execute is responsible for checking the value of the Terminated property to determine if the thread needs to exit.

A thread executes when Create is called if CreateSuspended set to false, or when Resume is first called after the thread is created if CreateSuspended set to true.

Note:	Do not use the properties and methods of other objects directly in the Execute method of a thread.  Instead, separate the use of other objects into a separate procedure call, and call that procedure by passing it as a parameter to the Synchronize method.


TThread::Resume

TThread	See also 	Example

Restarts the execution of a suspended thread.

void __fastcall Resume(void);

Description

Calls to Suspend can be nested; Resume must be called the same number of times Suspend was called before the thread will resume execution.


TThread::Suspend

TThread	See also

Pauses a running thread.

void __fastcall Suspend(void);

Description

Call Resume to resume execution. Calls to Suspend can be nested; Resume must be called the same number of times Suspend was called before the thread will resume execution.


TThread::Synchronize

TThread	See also 	Example

Executes Method within the main VCL thread.

typedef void __fastcall (__closure *TThreadMethod)(void);

void __fastcall Synchronize(TThreadMethod &Method);

Description

The Synchronize method causes the call specified by Method to be executed by the main VCL thread, avoiding multi-thread conflicts. If you are unsure whether a method call is thread-safe, call it from within the main VCL thread by passing it to the Synchronize method.

Note:	Execution of the thread is suspended while Method is executing in the main VCL thread.


TThread::Terminate

TThread	See also

Signals the thread to terminate by setting the Terminated property to true.

void __fastcall Terminate(void);

Description

The thread's Execute method and any methods that Execute calls should check Terminated periodically and exit when it's true.


TThread::WaitFor

TThread	See also

Waits for the thread to terminate and then returns the value of the ReturnValue property.

int __fastcall WaitFor(void);

Description

WaitFor doesn't return until the thread terminates, so the thread must exit either by finishing the Execute method or by exiting when the Terminated property is true. Don't call WaitFor in the context of the main VCL thread if the thread uses Synchronize. Doing so will either cause a deadlock, making it appear that the application has hung, or raise an EThread exception.

Synchronize waits for the main VCL thread to enter the message loop before allowing the method it is trying to synchronize to execute. If the main VCL thread has called WaitFor, it won't enter the message loop and Synchronize will never return. TThread detects that case and will raise an EThread exception in the thread causing it to terminate and, if not caught in the Execute method, the application will terminate as well. If Synchronize is already waiting on the main VCL thread when WaitFor is called, TThread can't intervene, and the application will deadlock.


Scope

Protected

Accessibility

Read-only


Scope

Protected


Hierarchy

TObject


TTimeField

Hierarchy	Properties	Methods	Events	See also

TTimeField represents a time field in a dataset.

Unit

db

Description

Time fields contain time values.

TTimeField introduces no new properties, events, or methods. It overrides the DataSize property to reflect the specifics of a field of type ftTime.

As a descendant of TDateTimeField, TTimeField includes many properties, methods, and events that are useful for managing the value and properties of a temporal field in a database.


TTimeField properties

TTimeField	Alphabetically	Legend

In TTimeField

DataSize

Derived from TDateTimeField

AsDateTime

AsFloat

AsString

AsVariant

DisplayFormat

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TTimeField properties

TTimeField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TTimeField::DataSize

TTimeField	Example

Indicates the amount of memory needed to store the value of a time field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a time field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For time fields, DataSize is always 4. This is the size of time values in the database tables, not the size of the TDateTime data type used to store and manipulate time values by TTimeField.


TTimeField events

TTimeField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TTimeField events

TTimeField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TTimeField methods

TTimeField	Alphabetically

In TTimeField

~TTimeField

Create

TTimeField

Derived from TField

Assign

AssignValue

Clear

Destroy

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTimeField methods

TTimeField	By object

~TTimeField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

Create

DefaultHandler

Destroy

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TTimeField

Validate


TTimeField::TTimeField

TTimeField	See also

Creates and initializes an instance of TTimeField.

__fastcall virtual TTimeField(Classes::TComponent* AOwner);

Description

It is seldom necessary to call TTimeField directly, because a time field object is instantiated automatically for all time fields in a dataset. When creating a TTimeField, use the new keyword.

After calling the parent class’s constructor, TTimeField sets the DataType property to ftTime.


TTimeField::~TTimeField

TTimeField

Frees the memory associated with the TTimeField object.

__fastcall virtual ~TTimeField(void) { }

Description

Do not call ~TTimeField directly. Instead, use the delete keyword on the object, which causes ~TTimeField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TDateTimeField


 TTimer

Hierarchy	Properties	Methods	Events

TTimer is an object that encapsulates the Windows API timer functions.

Unit

extctrls

Description

TTimer is a component that is used to simplify calling the Windows API timer functions SetTimer and KillTimer, and to simplify processing the WM_TIMER messages. Use one timer component for each timer in the application.

Timer properties and methods affect the functionality of the timer by providing information for the timer event. This information includes the timer interval, which corresponds to the parameter for the Windows API SetTimer function. The actual execution of the timer occurs through its OnTimer event.

Caution:	Limitations on the total number of timers system-wide are system dependent.


TTimer properties

TTimer	Alphabetically	Legend

In TTimer

Enabled

Interval

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TTimer properties

TTimer	By object	Legend

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Enabled

Interval

Name

Owner

Tag

VCLComObject


TTimer::Enabled

TTimer	See also 	Example

Controls whether the timer responds to timer events.

__property bool Enabled = {read=FEnabled, write=SetEnabled, default=1};

Description

Use Enabled to enable or disable the timer. If Enabled is true, the timer responds normally. If Enabled is false, the timer ignores the OnTimer event. The default is true.


TTimer::Interval

TTimer	See also 	Example

Determines the amount of time, in milliseconds, that passes before the timer component initiates another OnTimer event.

__property Cardinal Interval = {read=FInterval, write=SetInterval, default=1000};

Description

Interval determines how frequently the OnTimer event occurs. Each time the specified interval passes, the OnTimer event occurs.

Use Interval to specify any cardinal value as the interval between OnTimer events. The default value is 1000 (one second).

Note:	A 0 value is valid, however the timer won't call an OnTimer event for a value of 0.


TTimer events

TTimer	Alphabetically	Legend

In TTimer

OnTimer


TTimer events

TTimer	By object	Legend

OnTimer


TTimer::OnTimer

TTimer	See also 	Example

Occurs when a specified amount of time, determined by the Interval property, has passed.

__property Classes::TNotifyEvent OnTimer = {read=FOnTimer, write=SetOnTimer};

Description

Use OnTimer to write an event handler to execute an action at regular intervals.

The Interval property of a timer determines how frequently the OnTimer event occurs. Each time the specified interval passes, the OnTimer event occurs.


TTimer methods

TTimer	Alphabetically

In TTimer

~TTimer

TTimer

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTimer methods

TTimer	By object

~TTimer

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TTimer


TTimer::TTimer

TTimer

Instantiates a timer object.

__fastcall virtual TTimer(Classes::TComponent* AOwner);

Description

Do not call TTimer directly to instantiate a timer at runtime. Instead, use the new keyword, passing in an Owner component that is responsible for freeing the timer. Timers added at design time are created automatically.

TTimer allocates memory for a timer, and calls the parent class’s constructor method. Then it:

•	Initializes the Enabled property to true .

•	Initializes the Interval property to 1000.

•	Allocates a window handle for the timer passing it the timer window procedure which processes the WM_TIMER messages.


TTimer::~TTimer

TTimer

Disposes of a timer object.

__fastcall virtual ~TTimer(void);

Description

Do not call ~TTimer directly in an application. Instead, use the delete keyword.

~TTimer deactivates the timer by setting Enabled to false. Then it kills the timer by calling the Windows API KillTimer function and deallocates the timer window handle before calling the parent object’s destructor.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent


 TToolBar

Hierarchy	Properties	Methods	Events	See also

TToolBar manages tool buttons and other controls, arranging them in rows and automatically adjusting their sizes and positions.

Unit

comctrls

Description

TToolBar is a container for tool buttons (TToolButton). It provides an easy way to arrange and manage visual controls.

•	All tool buttons on a tool bar maintain a uniform width and height.

•	Other controls can sit on a tool bar. These controls (which are held in place by invisible tool buttons) maintain a uniform height.

•	Controls can automatically wrap around and start a new row when they do not fit horizontally on the tool bar.

•	The Flat property allows the background to show through the tool bar and gives pop-up borders to the tool buttons.

•	Spaces and dividers (which are in fact specially configured tool buttons) can group controls on the tool bar both visually and functionally.

Typically, the tool buttons correspond to items in an application’s menu and give the user more direct access to the application’s commands.


TToolBar properties

TToolBar	Alphabetically	Legend

In TToolBar

AutoSize

ButtonCount

ButtonHeight

Buttons

ButtonWidth

DisabledImages

Flat

HotImages

Images

Indent

List

RowCount

ShowCaptions

Wrapable

Derived from TToolWindow

BorderWidth

EdgeBorders

EdgeInner

EdgeOuter

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TToolBar properties

TToolBar	By object	Legend

Align

AutoSize

BorderWidth

BoundsRect

Brush

ButtonCount

ButtonHeight

Buttons

ButtonWidth

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DisabledImages

DragCursor

DragMode

EdgeBorders

EdgeInner

EdgeOuter

Enabled

Flat

Font

Handle

Height

HelpContext

Hint

HotImages

Images

Indent

Left

List

Name

Owner

Parent

ParentColor

ParentFont

ParentShowHint

ParentWindow

PopupMenu

RowCount

ShowCaptions

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc

Wrapable


TToolBar::AutoSize

TToolBar	See also

Changes the tool bar’s height to accommodate the controls in it.

__property bool AutoSize = {read=FAutoSize, write=SetAutoSize, default=0};

Description

If AutoSize is set to true, the height of the tool bar adjusts automatically so that the controls fit in it with no vertical margin.


TToolBar::ButtonCount

TToolBar	See also

Indicates the number of buttons in the tool bar.

__property int ButtonCount = {read=GetButtonCount, nodefault};

Description

ButtonCount gives the number of buttons in the Buttons array.


TToolBar::ButtonHeight

TToolBar	See also

Specifies the height of the controls in the tool bar.

__property int ButtonHeight = {read=FButtonHeight, write=SetButtonHeight, default=22};

Description

ButtonHeight represents the height, in pixels, of the controls in the tool bar.


TToolBar::Buttons

TToolBar	See also

Lists the tool buttons (TToolButton) in the tool bar.

__property TToolButton* Buttons[int Index] = {read=GetButton};

Description

Buttons maintains a list of TToolButton instances. All tool buttons that share a TToolBar parent have the same height and (except for separators and dividers) the same width. Other controls on a tool bar are held in place by invisible separators, which are automatically created and destroyed.

To add tool buttons to the tool bar at design time, select the tool bar, right-click, and choose New Button. To create a space (separator) between one button and the next, select New Separator. To create a divider between buttons, add a button and set its Style property to tbsDivider. Other controls may be added to the tool bar directly from the Component palette.


TToolBar::ButtonWidth

TToolBar	See also

Specifies the width of the tool buttons (TToolButton) in the tool bar.

__property int ButtonWidth = {read=FButtonWidth, write=SetButtonWidth, default=23};

Description

ButtonWidth represents the width, in pixels, of the TToolButton components in the tool bar. It has no effect on tool buttons whose Style property is set to tbsSeparator or tbsDivider.


TToolBar::DisabledImages

TToolBar	See also

Lists the images that can appear on disabled tool buttons.

__property Controls::TImageList* DisabledImages = {read=FDisabledImages, write=SetDisabledImages};

Description

DisabledImages contains a list of images that can appear on tool buttons when they are disabled. Each tool button’s ImageIndex property determines the specific image displayed on it. If DisabledImages is unassigned, disabled tool buttons display grayed versions of their regular images (specified by the Images property).


TToolBar::Flat

TToolBar	See also

Makes the tool bar transparent and eliminates tool-button borders.

__property bool Flat = {read=FFlat, write=SetFlat, default=0};

Description

If Flat is set to true, the tool bar and its tool buttons are transparent; background colors and graphics show through them. In addition, when Flat is true, tool buttons (TToolButton) on the tool bar have pop-up borders that appear only when the mouse is passed over the button.

Note:	If Flat is set to true, TToolBar requires version 4.70 or later of COMCTL32.DLL at both design time and runtime.


TToolBar::HotImages

TToolBar	See also

Lists the images that can appear on tool buttons when the mouse points to them.

__property Controls::TImageList* HotImages = {read=FHotImages, write=SetHotImages};

Description

HotImages contains a list of images that can appear on tool buttons when the mouse passes over them at runtime. Each tool button’s ImageIndex property determines the specific image displayed when the mouse points to it. If HotImages is unassigned, tool buttons retain their regular images (specified by the Images property) when pointed to.


TToolBar::Images

TToolBar	See also

Lists the images that can appear on tool buttons.

__property Controls::TImageList* Images = {read=FImages, write=SetImages};

Description

Images contains a list of images that can appear on the tool bar’s tool buttons. Each tool button’s ImageIndex property determines the specific image displayed on it. If Images is unassigned, no images are displayed on the tool buttons.


TToolBar::Indent

TToolBar

Creates a margin on the left side of the tool bar.

__property int Indent = {read=FIndent, write=SetIndent, default=0};

Description

Indent specifies, in pixels, the margin that separates the left edge of the tool bar from the controls within it.


TToolBar::List

TToolBar	See also

Aligns captions on the right and images on the left in tool buttons.

__property bool List = {read=FList, write=SetList, default=0};

Description

When List is false, tool buttons (TToolButton) appear in the tool bar with their images (if any) centered and their captions (if visible) underneath. Setting List to true aligns captions to the right and images to the left.


TToolBar::RowCount

TToolBar	See also

Indicates the number of rows in the tool bar.

__property int RowCount = {read=GetRowCount, nodefault};

Description

Reading RowCount returns the number of rows the tool buttons are arranged in.


TToolBar::ShowCaptions

TToolBar	See also	Example

Determines whether text captions are displayed on tool buttons.

__property bool ShowCaptions = {read=FShowCaptions, write=SetShowCaptions, default=0};

Description

If ShowCaptions is set to true, tool buttons appear in the tool bar with their captions displayed. Setting ShowCaptions to true may increase the size of the tool buttons.


TToolBar::Wrapable

TToolBar	See also

Enables automatic line-wrap for components in the tool bar.

__property bool Wrapable = {read=FWrapable, write=SetWrapable, default=1};

Description

If Wrapable is true, components automatically wrap around and form new rows when they do not fit horizontally in the tool bar.


TToolBar events

TToolBar	Alphabetically	Legend

In TToolBar

OnResize

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TToolBar events

TToolBar	By object	Legend

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnStartDrag


TToolBar::OnResize

TToolBar

Occurs when the tool bar is resized.

__property Classes::TNotifyEvent OnResize = {read=FOnResize, write=FOnResize};

Description

The OnResize event occurs whenever the TToolBar to is resized at runtime.


TToolBar methods

TToolBar	Alphabetically

In TToolBar

~TToolBar

TToolBar

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TToolBar methods

TToolBar	By object

~TToolBar

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TToolBar

Update

UpdateControlState


TToolBar::TToolBar

TToolBar 	See also

Creates and initializes a TToolBar instance.

__fastcall virtual TToolBar(Classes::TComponent* AOwner);

__fastcall TToolBar(HWND ParentWindow) : Toolwin::TToolWindow(ParentWindow) { }

Description

Call TToolBar indirectly, using the new keyword, to create a tool bar at runtime. Tool bars added to forms at design time are created automatically.

Pass a single Component as a parameter to provide the tool bar with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the tool bar in a non-VCL window. This syntax is used when the tool bar is implemented as an ActiveX control that is embedded in a non-VCL window.


TToolBar::~TToolBar

TToolBar	See also

Destroys the TToolBar instance and frees its memory

__fastcall virtual ~TToolBar(void);

Description

Do not call ~TToolBar directly. Instead, use the delete keyword on the object, which causes ~TToolBar to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TToolWindow


TToolButton

Hierarchy	Properties	Methods	Events	See also

TToolButton is a button control in a TToolBar object.

Unit

comctrls

Description

Use TToolButton to implement buttons in a tool bar. While other controls (including TButton and TSpeedButton) can be placed in tool bars, TToolButton utilizes special tool-bar features to simplify the configuration of buttons and offers added display options such as pop-up borders and transparency.

To place tool buttons on a tool bar at design time, select the tool bar, right-click, and choose New Button.


TToolButton properties

TToolButton	Alphabetically	Legend

In TToolButton

AllowAllUp

Down

DropDownMenu

Grouped

ImageIndex

Indeterminate

Style

Wrap

Derived from TControl

Align

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TToolButton properties

TToolButton	By object	Legend

Align

AllowAllUp

BoundsRect

Caption

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlState

ControlStyle

Cursor

DesignInfo

Down

DragCursor

DragMode

DropDownMenu

Enabled

Grouped

Height

Hint

ImageIndex

Indeterminate

Left

Name

Owner

Parent

ParentShowHint

PopupMenu

ShowHint

Style

Tag

Top

VCLComObject

Visible

Width

WindowProc

Wrap


TToolButton::AllowAllUp

TToolButton	See also

Indicates whether all the tool buttons in a group can be unselected at the same time.

__property bool AllowAllUp = {read=FAllowAllUp, write=FAllowAllUp, default=0};

Description

If AllowAllUp is set to true, all of the tool buttons in the group can be unselected. If AllowAllUp is set to false, at least one tool button in the group must be selected at any time. (Determine which tool button is initially selected by setting its Down property to true.)

AllowAllUp is effective only when Grouped is true and Style is set to tbsCheck. Changing the value of AllowAllUp for one button in a group automatically changes the value for all buttons in the group.


TToolButton::Down

TToolButton	See also

Specifies whether the button is selected (down) or unselected (up).

__property bool Down = {read=FDown, write=SetDown, default=0};

Description

Read Down to determine whether a tool button is selected. Setting Down to true at design time causes the button to be initially selected.

Tool buttons can remain Down only if Style is tbsCheck.


TToolButton::DropdownMenu

TToolButton	See also

Identifies a pop-up menu associated with the tool button.

__property Menus::TPopupMenu* DropdownMenu = {read=FDropdownMenu, write=SetDropdownMenu};

Description

Assign a value to DropdownMenu to make a menu appear when the button is pressed. (To display the menu programmatically, call the tool button’s Click method.) If the menu’s AutoPopup property is set to true, the menu appears automatically. If AutoPopup is false, display the menu by calling the menu’s Popup method in the tool button’s OnClick event handler.

When associating a drop-down menu with the tool button, set the Style to tbsDropDown.


TToolButton::Grouped

TToolButton	See also

Aggregates a sequence of adjacent tbsCheck buttons.

__property bool Grouped = {read=FGrouped, write=SetGrouped, default=0};

Description

When an unbroken sequence of adjacent tool buttons each has its Grouped property set to true and Style set to tbsCheck, then no more than one of the buttons can be selected at the same time. Selecting a grouped button at runtime unselects the other buttons in its group.

To create distinct groups of buttons within a tool bar, separate the groups with any of the following: tool buttons whose Grouped property is false, tool buttons whose Style property is not tbsCheck (tbsSeparator and tbsDivider buttons are useful for this), or controls other than tool buttons.


TToolButton::ImageIndex

TToolButton	See also

Determines which images appears on the tool button.

__property int ImageIndex = {read=FImageIndex, write=SetImageIndex, nodefault};

Description

The ImageIndex property determines which image—from TToolBar’s Images list—appears on the tool button. If TToolBar::DisabledImages and TToolBar::HotImages are defined, different images appear when the button is disabled and when the mouse pointer passes over the button.

These lists are zero-based; the first image is indexed by 0, the second by 1, and so forth. Since ImageIndex holds only a single integer value, the positions of the selected images must coincide on the different lists. For example, if ImageIndex = 2, the button displays the third image in each list.


TToolButton::Indeterminate

TToolButton	See also

Indicates that the tool button is neither selected nor unselected.

__property bool Indeterminate = {read=FIndeterminate, write=SetIndeterminate, default=0};

Description

Indeterminate provides a third state for tool buttons that are neither selected nor unselected. Set this property in program code to indicate that a button is inapplicable in a particular context. Buttons with the Indeterminate property set to true appear grayed.

When Indeterminate is set to true, Down is automatically set to false.


TToolButton::Style

TToolButton	See also	Example

Determines the style of the tool button.

enum TToolButtonStyle { tbsButton, tbsCheck, tbsDropDown, tbsSeparator, tbsDivider };

__property TToolButtonStyle Style = {read=FStyle, write=SetStyle, default=0};

Description

These are the possible values of Style:

Value	Meaning

tbsButton	The button appears and functions like a normal speed button.

tbsCheck	Clicking the button toggles the Down property. Once selected, the button remains selected until clicked again.

tbsDropDown	The button displays a downward-pointing arrow (suitable for accessing a drop-down menu).

tbsSeparator	The button appears as an empty space on the tool bar (used to separate other controls).

tbsDivider	The button appears as a vertical line on the tool bar (used to separate other controls).


TToolButton::Wrap

TToolButton	See also

Forces a new row after the tool button.

__property bool Wrap = {read=FWrap, write=SetWrap, default=0};

Description

Set Wrap to true to make the tool button the last in its row. Wrap is disabled when TToolBar::Wrapable is true.


TToolButton events

TToolButton	Alphabetically	Legend

Derived from TControl

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TToolButton events

TToolButton	By object	Legend

OnClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TToolButton methods

TToolButton	Alphabetically

In TToolButton

~TToolButton

TToolButton

Derived from TGraphicControl

Derived from TControl

BeginDrag

BringToFront

Click

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Invalidate

Perform

Refresh

Repaint

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

Update

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TToolButton methods

TToolButton	By object

~TToolButton

Assign

BeginDrag

BringToFront

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Click

ClientToScreen

DefaultHandler

DestroyComponents

Destroying

Dispatch

DragDrop

Dragging

EndDrag

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTextBuf

GetTextLen

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

Perform

Refresh

RemoveComponent

Repaint

SafeCallException

ScreenToClient

SendToBack

SetBounds

SetTextBuf

Show

TToolButton

Update


TToolButton::TToolButton

TToolButton 	Example

Creates and initializes a TToolButton instance.

__fastcall virtual TToolButton(Classes::TComponent* AOwner);

Description

Call TToolButton indirectly, using the new keyword, to create a TToolButton object at runtime.  Tool buttons added at design time are created automatically.


TToolButton::~TToolButton

TToolButton

~TToolButton frees the memory associated with the TToolButton object.

__fastcall virtual ~TToolButton(void) { }

Description

Do not call ~TToolButton directly. Instead, use the delete keyword on the object, which causes ~TToolButton to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TGraphicControl


TToolWindow

Hierarchy	Properties	Methods	See also

TToolWindow is the abstract ancestor for windowed controls that require a custom client area and edge borders.

Unit

toolwin

Description

TToolWindow is the ancestor of the TCoolBar and TToolBar components, which facilitate the arrangement of buttons and other visual controls.


TToolWindow properties

TToolWindow	Alphabetically	Legend

In TToolWindow

BorderWidth

EdgeBorders

EdgeInner

EdgeOuter

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TToolWindow properties

TToolWindow	By object	Legend

Align

BorderWidth

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

EdgeBorders

EdgeInner

EdgeOuter

Enabled

Handle

Height

HelpContext

Hint

Left

Name

Owner

Parent

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowProc


TToolWindow::BorderWidth

TToolWindow

Determines the width of the control’s internal border.

__property int BorderWidth = {read=FBorderWidth, write=SetBorderWidth, default=0};

Description

The BorderWidth property creates a margin between the inner edge of the TToolWindow and the controls inside it. If BorderWidth is too large, the internal controls will not be visible.


TToolWindow::EdgeBorders

TToolWindow	See also

Determines which sides of the control have visible borders.

enum TEdgeBorder { ebLeft, ebTop, ebRight, ebBottom };

typedef Set<TEdgeBorder, ebLeft, ebBottom> TEdgeBorders;

__property TEdgeBorders EdgeBorders = {read=FEdgeBorders, write=SetEdgeBorders, default=15};

Description

Use the EdgeBorders property to add or remove borders. The appearance of the borders can be set with the EdgeInner and EdgeOuter properties.


TToolWindow::EdgeInner

TToolWindow	See also

Determines the border style for the control’s inner edge.

enum TEdgeStyle { esNone, esRaised, esLowered };

__property TEdgeStyle EdgeInner = {read=FEdgeInner, write=SetEdgeInner, default=1};

Description

The possible values of EdgeInner are:

Value	Meaning

esNone	No inner edge is displayed.

esRaised	The inner edge is raised.

esLowered	The inner edge is lowered.

Use EdgeInner with EdgeOuter to give the component a three-dimensional look.


TToolWindow::EdgeOuter

TToolWindow	See also

Determines the border style for the control’s outer edge.

enum TEdgeStyle { esNone, esRaised, esLowered };

__property TEdgeStyle EdgeOuter = {read=FEdgeOuter, write=SetEdgeOuter, default=2};

Description

The possible values of EdgeOuter are:

Value	Meaning

esNone	No outer edge is displayed.

esRaised	The outer edge is raised.

esLowered	The outer edge is lowered.

Use EdgeOuter with EdgeInner to give the component a three-dimensional look.


TToolWindow methods

TToolWindow	Alphabetically

In TToolWindow

~TToolWindow

TToolWindow

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TToolWindow methods

TToolWindow	By object

~TToolWindow

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TToolWindow

Update

UpdateControlState


TToolWindow::TToolWindow

TToolWindow

Creates and initializes a TToolWindow instance.

__fastcall virtual TToolWindow(Classes::TComponent* AOwner);

__fastcall TToolWindow(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Call TToolWindow indirectly, using the new keyword, to instantiate a tool window at runtime. Tool windows placed at design time are created automatically.

Pass a single Component as a parameter to provide the tool window with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the tool window in a non-VCL window. This syntax is used when the tool window is implemented as an ActiveX control that is embedded in a non-VCL window.


TToolWindow::~TToolWindow

TToolWindow

~TToolWindow frees the memory associated with the TToolWindow object.

__fastcall virtual ~TToolWindow(void) { }

Description

Do not call ~TToolWindow directly. Instead, use the delete keyword on the object, which causes ~TToolWindow to be invoked automatically.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


 TTrackBar

Hierarchy	Properties	Methods	Events	See also

TTrackBar is a wrapper for the Windows track bar control.

Unit

comctrls

Description

Use TTrackBar to put a track bar on a form. A track bar represents a position along a continuum using a slider and, optionally, tick marks. A track bar can also display a selected range marked by triangular ticks at the starting and ending positions of the selection.

During program execution, the slider can be moved to the desired position by dragging it with the mouse or by clicking the mouse on the bar. To use the keyboard to move the slider, press the arrow keys or the PageUp and PageDown keys.


TTrackBar properties

TTrackBar	Alphabetically	Legend

In TTrackBar

Frequency

LineSize

Max

Min

Orientation

PageSize

Position

SelEnd

SelStart

TickMarks

TickStyle

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

DragCursor

DragMode

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TTrackBar properties

TTrackBar	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

Enabled

Frequency

Handle

Height

HelpContext

Hint

Left

LineSize

Max

Min

Name

Orientation

Owner

PageSize

Parent

ParentCtl3D

ParentShowHint

ParentWindow

PopupMenu

Position

SelEnd

SelStart

ShowHint

Showing

TabOrder

TabStop

Tag

TickMarks

TickStyle

Top

VCLComObject

Visible

Width

WindowProc


TTrackBar::Frequency

TTrackBar	See also

Specifies the increment between tick marks on the track bar.

__property int Frequency = {read=FFrequency, write=SetFrequency, nodefault};

Description

Use Frequency to specify the spacing of the tick marks, using the logical units used by the Position property. For example, a Frequency of 5 sets a tick mark at every fifth possible increment. To provide visual feedback about the units used by the track bar, set Frequency to LineSize or PageSize.

Note:	If the value of the TickStyle property is not set to tsAuto, the value of Frequency is ignored.


TTrackBar::LineSize

TTrackBar	See also

Indicates the amount the value of Position changes when the user presses the arrow keys.

__property int LineSize = {read=FLineSize, write=SetLineSize, default=1};

Description

Use LineSize to specify the distance along the slider that represents a single unit. The current Position is marked by a slider. The right and down arrow keys increment the value of Position by LineSize, and the left and up arrow keys decrement the value of Position by LineSize.

Use the PageSize property to set the number of ticks moved using the PageUp and PageDown keys.


TTrackBar.Max

TTrackBar	See also

Specifies the maximum Position of a TTrackBar.

__property int Max = {read=FMax, write=SetMax, default=10};

Description

Use Max to set an upper limit to the value that can be represented using the track bar. A slider indicates the current Position in a range between Min and Max.


 TTrackBar.Min

TTrackBar	See also

Specifies the minimum Position of a TTrackBar.

__property int Min = {read=FMin, write=SetMin, default=0};

Description

Use Min to set a lower limit to the value that can be represented using the track bar. A slider indicates the current Position in a range between Min and Max.


TTrackBar::Orientation

TTrackBar	See also

Specifies whether the track bar is horizontal or vertical.

enum TTrackBarOrientation { trHorizontal, trVertical };

__property TTrackBarOrientation Orientation = {read=FOrientation, write=SetOrientation, nodefault};

Description

Set Orientation to the desired orientation of the track bar. Orientation has these possible values:

Value	Meaning

tbHorizontal	The long edge of the track is parallel to the top of the form. The Min position is on the left and the Max position is on the right.

tbVertical	The long edge of the track is parallel to the side of the form. The Min position is on the top and the Max position is on the bottom.


TTrackBar::PageSize

TTrackBar	See also

Specifies the amount Position is changed when the PageUp or PageDown key is pressed, or when the bar is clicked.

__property int PageSize = {read=FPageSize, write=SetPageSize, default=2};

Description

Set PageSize to the distance along the track bar that corresponds to a single view. The current Position is marked by a slider. The PageUp key increments the value of Position by PageSize, and PageDown key decrements the value of Position by PageSize.

Use the LineSize property to set the number of ticks moved using the arrow keys.


TTrackBar::Position

TTrackBar	See also

Contains the current position of the slider of a TTrackBar.

__property int Position = {read=FPosition, write=SetPosition, nodefault};

Description

Read Position to determine the current value represented by the track bar. Position is a value in the range between Min and Max (inclusive). Set Position to programmatically move the slider of the track bar to a new value.


TTrackBar::SelEnd

TTrackBar	See also

Specifies the position of the end point of the selection range.

__property int SelEnd = {read=FSelEnd, write=SetSelEnd, nodefault};

Description

Set SelEnd to determine the length of a selection that begins at SelStart. The track bar indicates a selection range on the bar by placing special tick marks at the positions specified by the SelStart and SelEnd properties and high-lighting the selected portion of the bar.

SelEnd must be greater than or equal to Position. If SelEnd is set to a value less than Position, Position changes to SelEnd. SelEnd must be greater than or equal to SelStart. If SelEnd is the same as SelStart, there is no selection, and the value of Position is the same as SelStart and SelEnd.


TTrackBar::SelStart

TTrackBar	See also

Specifies the position of the starting point of the selection range.

__property int SelStart = {read=FSelStart, write=SetSelStart, nodefault};

Description

Set SelStart to determine the beginning of a selection that runs to SelEnd. The track bar indicates a selection range on the bar by placing special tick marks at the positions specified by the SelStart and SelEnd properties and high-lighting the selected portion of the bar.

SelStart must be less than or equal to Position. If SelStart is set to a value greater than Position, Position changes to SelStart. SelStart must be less than or equal to SelEnd. If SelStart is the same as SelEnd, there is no selection, and the value of Position is the same as SelStart and SelEnd.


TTrackBar::TickMarks

TTrackBar	See also

Specifies the location of the tick marks.

enum TTickMark { tmBottomRight, tmTopLeft, tmBoth };

__property TTickMark TickMarks = {read=FTickMarks, write=SetTickMarks, nodefault};

Description

Set TickMarks to specify where the tick marks should be drawn. TickMarks has these possible values:

Value	Meaning

tmBottomRight	Tick marks are on the bottom or right of the track bar, depending of the value of Orientation.

tmTopLeft	Tick marks are on the top or left of the track bar, depending of the value of Orientation.

tmBoth	Tick marks are on both sides of the track bar.

If the TickStyle property is tsNone, the value of TickMarks is ignored.


TTrackBar::TickStyle

TTrackBar	See also

Specifies how tick marks are placed on the track bar.

enum TTickStyle { tsNone, tsAuto, tsManual };

__property TTickStyle TickStyle = {read=FTickStyle, write=SetTickStyle, nodefault};

Description

Set TickStyle to specify whether the track bar should display tick marks, and if so, how those tick marks are set. TickStyle has these possible values:

Value	Meaning

tsAuto	Tick marks are automatically displayed at increments equal to the value of the Frequency property.

tsManual	Tick marks are displayed at the Min and Max values. Additional tick marks can be set using the SetTick method.

tsNone	No tick marks are displayed.


TTrackBar events

TTrackBar	Alphabetically	Legend

In TTrackBar

OnChange

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnDragDrop

OnDragOver

OnEndDrag

OnStartDrag


TTrackBar events

TTrackBar	By object	Legend

OnChange

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

OnStartDrag


TTrackBar::OnChange

TTrackBar	See also

Occurs immediately after the value of Position changes.

__property Classes::TNotifyEvent OnChange = {read=FOnChange, write=FOnChange};

Description

Write an OnChange event handler to take specific action whenever the position of the slider may have changed. For example, if the track bar is being used to control another object, update the other object from an OnChange event handler.


TTrackBar methods

TTrackBar	Alphabetically

In TTrackBar

~TTrackBar

SetTick

TTrackBar

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTrackBar methods

TTrackBar	By object

~TTrackBar

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

SetTick

Show

TTrackBar

Update

UpdateControlState


TTrackBar::TTrackBar

TTrackBar	See also

Creates and initializes an instance of TTrackBar.

__fastcall virtual TTrackBar(Classes::TComponent* AOwner);

__fastcall TTrackBar(HWND ParentWindow) : Controls::TWinControl(ParentWindow) { }

Description

Call TTrackBar indirectly, using the new keyword, to instantiate a TTrackBar object at runtime. Track bars placed on forms at design time are created automatically.

Pass a single Component as a parameter to provide the trackbar with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the trackbar in a non-VCL window. This syntax is used when the trackbar is implemented as an ActiveX control that is embedded in a non-VCL window.

TTrackBar allocates memory and initializes the following properties:

•	ControlStyle is set to [csCaptureMouse, csClickEvents, csSetCaption].

•	Frequency is set to 1.

•	Height is set to 45 and Width to 150.

•	LineSize is set to 1 and PageSize to 2.

•	Max is set to 10 and Min to 0.

•	Orientation is set to trHorizontal.

•	TickMarks is set to tbBottomRight and TickStyle to tsAuto.

•	TabStop is set to true.


TTrackBar::SetTick

TTrackBar	See also

Adds a tick mark to the track bar at a specified location.

void __fastcall SetTick(int Value);

Description

Use SetTick to place a tick mark on the bar at the position that corresponds to the Value parameter. Tick marks specified in this manner are only displayed when the TickStyle is set to tsManual.


TTrackBar::~TTrackBar

TTrackBar

Frees the memory associated with the TTrackBar object.

__fastcall virtual ~TTrackBar(void) { }

Description

Do not call ~TTrackBar directly. Instead, use the delete keyword on the object, which causes ~TTrackBar to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl


TTreeNode

Hierarchy	Properties	Methods	See also

TTreeNode describes an individual node in a tree view control.

Unit

comctrls

Description

Each node in a tree view control consists of a label and an optional bitmapped image. Each item can be the parent of a list of subitems. By clicking an item, the user can expand or collapse the associated list of subitems.


TTreeNode properties

TTreeNode	Alphabetically	Legend

In TTreeNode

AbsoluteIndex

Count

Cut

Data

Deleting

DropTarget

Expanded

Focused

Handle

HasChildren

ImageIndex

Index

IsVisible

Item

ItemId

Level

OverlayIndex

Owner

Parent

Selected

SelectedIndex

StateIndex

Text

TreeView


TTreeNode properties

TTreeNode	By object	Legend

AbsoluteIndex

Count

Cut

Data

Deleting

DropTarget

Expanded

Focused

Handle

HasChildren

ImageIndex

Index

IsVisible

Item

ItemId

Level

OverlayIndex

Owner

Parent

Selected

SelectedIndex

StateIndex

Text

TreeView


TTreeNode::AbsoluteIndex

TTreeNode	See also

Indicates the index of the tree node relative to the first tree node in a tree node.

__property int AbsoluteIndex = {read=GetAbsoluteIndex, nodefault};

Description

Use AbsoluteIndex to determine absolute position of a node in a tree nodes object. The first tree node in a tree nodes object has an index of 0 and subsequent nodes are numbered sequentially. If a node has any children, its AbsoluteIndex is one less than the index of its first child.


TTreeNode::Count

TTreeNode	See also

Indicates the number of direct descendants of a tree node.

__property int Count = {read=GetCount, nodefault};

Description

Use Count to determine how many child nodes belong to a tree node. Count includes only immediate children, and not their descendants. Count can be useful when iterating through the children of a tree node.


TTreeNode.Cut

TTreeNode	See also

Indicates if the tree node object is drawn as if selected as part of a cut and paste operation.

__property bool Cut = {read=GetCut, write=SetCut, nodefault};

Description

Use Cut to alter the appearance of the tree node when it is selected as part of a cut and paste operation.


TTreeNode::Data

TTreeNode	Example

Points to application-defined data associated with the tree node.

__property void * Data = {read=FData, write=SetData};

Description

Use the Data property to associate data with a tree node. Data allows applications to quickly access information about the entity represented by the node.


TTreeNode::Deleting

TTreeNode	See also

Indicates whether a node's Destroy method has been called and it is in the process of being deleted.

__property bool Deleting = {read=FDeleting, nodefault};

Description

Use Deleting to avoid recursively trying to delete a node in response to events that occur as a result of the node being deleted.


TTreeNode::DropTarget

TTreeNode	See also

Indicates whether the tree node is drawn as a drag and drop target.

__property bool DropTarget = {read=GetDropTarget, write=SetDropTarget, nodefault};

Description

Use DropTarget to indicate that the node is a drag and drop target. When DropTarget is true, the node is drawn in a style used to indicate a drag and drop target.

Note:	Setting DropTarget to true does cause the node to automatically accept dragged objects when they are released. The application must still implement the drop behavior.


TTreeNode::Expanded

TTreeNode	See also

Specifies whether the tree node is expanded.

__property bool Expanded = {read=GetExpanded, write=SetExpanded, nodefault};

Description

When a tree node is expanded, the minus button is shown if the ShowButtons property of the tree view is true and child nodes are displayed. Set Expanded to true to display the children of a node. Set Expanded to false to collapse the node, hiding all of its descendants.


TTreeNode::Focused

TTreeNode	See also

Indicates whether the node appears to have focus.

__property bool Focused = {read=GetFocused, write=SetFocused, nodefault};

Description

Tree view nodes are not windowed controls and so can’t receive input focus. However, they can be edited by the user when the tree view control has focus. When Focused is true, the node is surrounded by a standard focus rectangle and the user can edit the label. Use Focused to determine if a particular node in a tree view can currently be edited by the user.


TTreeNode::Handle

TTreeNode	See also

Contains the window Handle of the tree view that contains the node.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Use Handle to obtain the handle of the tree view that owns the node. This handle can be passed as a parameter to Windows API function calls that require a handle to the tree view.


TTreeNode::HasChildren

TTreeNode	See also

Indicates whether a node has any children.

__property bool HasChildren = {read=GetChildren, write=SetChildren, nodefault};

Description

HasChildren is true if the node has subnodes, or false if the node has no subnodes. If ShowButtons of the tree view is true, and HasChildren is true, a plus (+) button will appear to the left of the node when it is collapsed, and a minus (-) button will appear when the node is expanded.

Note:	If a node has no children, setting HasChildren to true will show a (+) plus button, but will not add any child nodes and the node cannot be expanded.


TTreeNode::ImageIndex

TTreeNode	See also

Specifies which image is displayed when a node is in its normal state and is not currently selected.

__property int ImageIndex = {read=FImageIndex, write=SetImageIndex, nodefault};

Description

Use the ImageIndex property with the Images property of the tree view to specify the image for the node in it’s normal state.


TTreeNode::Index

TTreeNode	See also

Specifies the position of the node in the list of child nodes maintained by its parent node.

__property int Index = {read=GetIndex, nodefault};

Description

Use Index to determine the position of the node relative to its sibling nodes. The first child of the parent node has an Index value of 0, and subsequent children are indexed sequentially.


TTreeNode::IsVisible

TTreeNode	See also

Indicates whether the tree node is currently visible in the tree view image.

__property bool IsVisible = {read=IsNodeVisible, nodefault};

Description

A node is visible if it is on level 0 or if all its parents are expanded. IsVisible indicates whether the node is part of the current tree view image. It does not indicate whether or not the node is scrolled into view when the tree view image is larger than the size of the tree view control.


TTreeNode::Item

TTreeNode	See also 	Example

Provides access to a child node by its position in the list of child nodes.

__property TTreeNode* Item[int Index] = {read=GetItem, write=SetItem};

Description

Use Item to access a child node based on its Index property. The first child node has an index of 0, the second an index of 1, and so on.


TTreeNode::ItemId

TTreeNode	See also

Contains a handle of type HTreeItem that uniquely identifies each node in a tree view.

__property HTREEITEM ItemId = {read=FItemId};

Description

Use this property to reference the nodes when making Windows API calls or calling the GetNode method of the TTreeNodes that owns the item.


TTreeNode::Level

TTreeNode	See also

Indicates the level of indentation of a node within the tree view control.

__property int Level = {read=GetLevel, nodefault};

Description

The value of Level is 0 for nodes on the top level. The value of Level is 1 for their children, and so on.


TTreeNode::OverlayIndex

TTreeNode	See also

Determines which image from the image list is used as an overlay mask.

__property int OverlayIndex = {read=FOverlayIndex, write=SetOverlayIndex, nodefault};

Description

An overlay mask is an image drawn transparently over another image in the tree view. For example, to indicate that a node is no longer available, use an overlay image that puts an X over the current node's image.


TTreeNode::Owner

TTreeNode	See also

Indicates which tree nodes object contains the tree node.

__property TTreeNodes* Owner = {read=FOwner};

Description

Use the Owner property to determine the owner of the tree node. Do not confuse Owner with the TreeView property. Owner is the list of nodes used by the tree view to manage its nodes. The TreeView property is the tree view that uses that list.


TTreeNode::Parent

TTreeNode	See also 	Example

Identifies the parent node of the tree node.

__property TTreeNode* Parent = {read=GetParent};

Description

A Parent node is one level higher than the node and contains the node as a subnode.


TTreeNode::Selected

TTreeNode	See also

Determines whether the node is selected.

__property bool Selected = {read=GetSelected, write=SetSelected, nodefault};

Description

Set Selected to true to select the node. The appearance of a selected node depends on whether it has the focus and on whether the system colors are used for selection. When a node becomes selected, the tree view's OnChanging and OnChanged events are triggered.


TTreeNode::SelectedIndex

TTreeNode	See also

Specifies the index in the tree view’s image list of the image displayed for the node when it is selected.

__property int SelectedIndex = {read=FSelectedIndex, write=SetSelectedIndex, nodefault};

Description

Use the SelectedIndex property to specify an image to display when the tree node is selected.


TTreeNode::StateIndex

TTreeNode	See also

Indicates which image from the StateImages list to display for the node.

__property int StateIndex = {read=FStateIndex, write=SetStateIndex, nodefault};

Description

Use StateIndex to display an additional image for the node that reflects state information. If StateIndex is -1 then no state image is drawn.


TTreeNode::Text

TTreeNode	See also

Specifies the label that identifies a tree node.

__property System::AnsiString Text = {read=FText, write=SetText};

Description

Use Text to specify the string that is displayed in the tree view. The value of Text can be assigned directly at run-time or can be set within the TreeView Items Editor while modifying the Items property of the TTreeView component. If the tree view allows users to edit its nodes, read Text to determine the value given the node by the user.


TTreeNode::TreeView

TTreeNode	See also

Specifies the tree view that displays the node.

__property TCustomTreeView* TreeView = {read=GetTreeView};

Description

Use TreeView to determine the tree view associated with the tree node.


TTreeNode methods

TTreeNode	Alphabetically

In TTreeNode

~TTreeNode

AlphaSort

Assign

Collapse

CustomSort

Delete

DeleteChildren

DisplayRect

EditText

EndEdit

Expand

GetFirstChild

GetHandle

GetLastChild

GetNext

GetNextChild

GetNextSibling

GetNextVisible

GetPrev

GetPrevChild

GetPrevSibling

GetPrevVisible

HasAsParent

IndexOf

MakeVisible

MoveTo

TTreeNode

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TTreeNode methods

TTreeNode	By object

~TTreeNode

AlphaSort

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Collapse

CustomSort

DefaultHandler

Delete

DeleteChildren

Dispatch

DisplayRect

EditText

EndEdit

Expand

FieldAddress

Free

FreeInstance

GetFirstChild

GetHandle

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetLastChild

GetNamePath

GetNext

GetNextChild

GetNextSibling

GetNextVisible

GetPrev

GetPrevChild

GetPrevSibling

GetPrevVisible

HasAsParent

IndexOf

InheritsFrom

InitInstance

InstanceSize

MakeVisible

MethodAddress

MethodName

MoveTo

NewInstance

SafeCallException

TTreeNode


TTreeNode::AlphaSort

TTreeNode	See also

Sorts the node’s children alphabetically based on their Text property.

bool __fastcall AlphaSort(void);

Description

Call AlphaSort to sort the subtree of the tree view alphabetically. If successful, the method returns true.


TTreeNode::Assign

TTreeNode	See also

Copies the properties of another tree view node.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

If the Source parameter is a TTreeNode object, Assign copies the Text, Data, ImageIndex, SelectedIndex, OverlayIndex, Focused, DropTarget, Cut, and HasChildren properties from the source node. If Source is any other type of object, Assign calls its parent class's method, which copies information from any object that can copy to a tree node in its AssignTo method.

Note:	While Assign copies the HasChildren property, it does not copy the child nodes. Be sure to copy any descendants after assigning the properties of another node that has children.


TTreeNode::Collapse

TTreeNode	See also

Collapses a node.

void __fastcall Collapse(bool Recurse);

Description

When a node is collapsed, all of its subnodes are hidden. The plus button may be displayed, depending on whether the tree view's ShowButtons property is set. If Recurse is true, then all subnodes will be collapsed as well. When the node is next expanded the children will still be collapsed. If Recurse is false, the child nodes won't be collapsed and the next time the node is expanded, the children will be in the same state as when Collapse was called.


TTreeNode::TTreeNode

TTreeNode	See also

Creates an instance of TTreeNode.

TTreeNode* __fastcall GetParent(void);

Description

Call TTreeNode to instantiate a tree node at runtime. Nodes added to a tree view control at design time are created automatically. Use the methods of the TTreeNodes object instead to create nodes as part of an existing tree view.

After calling the parent object’s constructor, TTreeNode sets the OverlayIndex and StateIndex properties to -1 and then sets the Owner property of the tree node to the AOwner TTreeNodes object.


TTreeNode::CustomSort

TTreeNode	See also 	Example

Sorts the descendants based using a customized ordering function.

bool __fastcall CustomSort(PFNTVCOMPARE SortProc, int Data);

Description

Use CustomSort to sort the descendants of a tree view nodes where the sort order is defined by the SortProc parameter. The lParam1 and lParam2 parameters of the sort procedure can be cast to TTreeNode objects are compared. The lParamSort parameter of the sort procedure is the value of Data parameter of CustomSort. The sort procedure should return a value less than 0 if lParam1 should come before lParam2, should return 0 if the two values are equivalent, and should return a value greater than 0 if lParam1 should follow lParam2.

If the SortProc parameter is NULL, the AlphaSort method is called.


TTreeNode::Delete

TTreeNode	See also

Destroys the node and all its children.

void __fastcall Delete(void);

Description

Use the Delete method to delete a tree node and free all associated memory.


TTreeNode::DeleteChildren

TTreeNode	See also

Deletes all children of the node.

void __fastcall DeleteChildren(void);

Description

Use the DeleteChildren method to delete all children of a tree node, freeing all associated memory.


TTreeNode::~TTreeNode

TTreeNode	See also

Destroys the tree node object.

__fastcall virtual ~TTreeNode(void);

Description

Do not call ~TTreeNode directly in an application. Instead, use the Delete method. Delete removes the image of the node and all its children from the tree view window, and guards against recursive deletes that could arise from the resulting Windows messages.


TTreeNode::DisplayRect

TTreeNode	See also

Returns the bounding rectangle for a tree node.

Windows::TRect __fastcall DisplayRect(bool TextOnly);

Description

If the TextOnly parameter is true, the bounding rectangle includes only the text of the node. Otherwise, it includes the entire line that the node occupies in the tree-view control.


TTreeNode::EditText

TTreeNode	See also

Begins in-place editing of the specified node's text, replacing the text of the node with a single-line edit control containing the text.

bool __fastcall EditText(void);

Description

Call EditText to allow the user to edit the node’s label. This method implicitly sets the Selected and Focused properties to true. When EditText is called, the tree view's OnEditing event is triggered.


TTreeNode::EndEdit

TTreeNode	See also

Ends the editing of a node's label.

void __fastcall EndEdit(bool Cancel);

Description

Call EndEdit to take the node out of edit mode. If the Cancel parameter is true, all changes made by the user are discarded. If Cancel is false, EndEdit updates the node’s Text property and the tree view’s OnEdited event occurs.


TTreeNode::Expand

TTreeNode	See also

Expands the node to display all child nodes.

void __fastcall Expand(bool Recurse);

Description

When a node is expanded, its immediate subnodes are displayed. The minus '-' button may be displayed, depending on whether the tree view's ShowButtons property is set. If Recurse is true, all descendants of the immediate subnodes are expanded as well.


TTreeNode::GetFirstChild

TTreeNode	See also

Returns the first child node of a tree node.

TTreeNode* __fastcall getFirstChild(void);

Description

Call GetFirstChild to access the first child node of the tree view node. If the node has no children, GetFirstChild returns NULL.

Note:	GetFirstChild returns the same value as Item[0].


TTreeNode::GetHandle

TTreeNode	See also

Returns the Handle property.

HWND __fastcall GetHandle(void);

Description

Calling GetHandle is the same as reading the Handle property.


TTreeNode::GetLastChild

TTreeNode	See also

Returns the last immediate child node of the calling node.

TTreeNode* __fastcall GetLastChild(void);

Description

Call GetLastChild to find the last immediate child of a node. If the calling node has no children, GetLastChild returns NULL. GetLastChild returns the same value as Item[Count-1].


TTreeNode::GetNext

TTreeNode	See also 	Example

Returns the next node after the calling node in the tree view.

TTreeNode* __fastcall GetNext(void);

Description

If the calling node is the last node, GetNext returns NULL. It returns the next node including nodes that aren't visible and child nodes. To get the next node at the same level as the calling node, use GetNextSibling. To get the next visible node, use GetNextVisible.


TTreeNode::GetNextChild

TTreeNode	See also 	Example

Returns the next child node after Value.

TTreeNode* __fastcall GetNextChild(TTreeNode* Value);

Description

Call GetNextChild to locate the next node in the list of immediate children of the tree view node. If the calling node has no children or there is no node after Value, GetNextChild returns NULL.


TTreeNode::GetNextSibling

TTreeNode	See also

Returns the next node in the tree view at the same level as the calling node.

TTreeNode* __fastcall getNextSibling(void);

Description

GetNextSibling will return the next node, regardless of whether it's visible. To find the next node in the tree view including child nodes, use GetNext.


TTreeNode::GetNextVisible

TTreeNode	See also

Returns the next visible node in the tree view after the calling node.

TTreeNode* __fastcall GetNextVisible(void);

Description

Use GetNextVisible when iterating through all the visible nodes in the tree view. A node is visible if all its parent nodes are expanded.


TTreeNode::GetPrev

TTreeNode	See also

Returns the previous node in the tree view before the calling node.

TTreeNode* __fastcall GetPrev(void);

Description

GetPrev will return the previous node whether or not it is visible. To get the previous visible node, use GetPrevVisible.


TTreeNode::GetPrevChild

TTreeNode	See also 	Example

Returns the previous child node before Value.

TTreeNode* __fastcall GetPrevChild(TTreeNode* Value);

Description

Call GetPrevChild to locate the previous node in the list of immediate children of the tree view node. If the calling node has no children or there is no node before Value, GetPrevChild returns NULL.


TTreeNode::GetPrevSibling

TTreeNode	See also

Returns the previous node before the calling node and at the same level.

TTreeNode* __fastcall getPrevSibling(void);

Description

GetPrevSibling returns the previous sibling node, regardless of whether it's visible. To find the previous node in the tree view including all levels, use GetPrev.


TTreeNode::GetPrevVisible

TTreeNode	See also

Returns the previous visible node before the calling node.

TTreeNode* __fastcall GetPrevVisible(void);

Description

To get the previous node, including nonvisible, use GetPrev.


TTreeNode::HasAsParent

TTreeNode	See also

Returns true if Value is a parent node of the calling node.

bool __fastcall HasAsParent(TTreeNode* Value);

Description

Use the HasAsParent method to determine if a node is a parent to a particular node.


TTreeNode::IndexOf

TTreeNode	See also

Returns the position of an immediate child node of the calling node.

int __fastcall IndexOf(TTreeNode* Value);

Description

Call IndexOf to obtain the position of a child node among the children of the calling node. If Value isn't an immediate child of the calling node, IndexOf returns -1. The first child node has an index on 0, the second an index of 1, and so on.


TTreeNode::MakeVisible

TTreeNode	See also

Expands the parent nodes of a node.

void __fastcall MakeVisible(void);

Description

If a node's parent node(s) are collapsed and the node isn't visible, MakeVisible will expand the nodes parents to make the node visible.


TTreeNode::MoveTo

TTreeNode	See also	Example

Moves the node to another location in the tree view.

virtual void __fastcall MoveTo(TTreeNode* Destination, TNodeAttachMode Mode);

Description

The Destination parameter determines where to move the node. The Mode parameter is of type TNodeAttachMode and specifies how the node is to be reattached. These are the possible values for the Mode parameter:

Value	Meaning

naAdd	Adds the node to the end of the list.

naAddFirst	Adds the node at the beginning of the list.

naAddChild	Adds the node as a child of the destination at the end of the child list.

naAddChildFirst	Adds the node as a child at the beginning of the child list of the destination.

naInsert	Insert the node after the destination node.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


TTreeNodes

Hierarchy	Properties	Methods	See also

TTreeNodes maintains a list of tree nodes in a tree view control.

Unit

comctrls

Description

The Items property of the tree view control is a TTreeNodes object and maintains the collection of nodes in the tree view. Nodes can be added, deleted, inserted, and moved within the tree view. Access the nodes in the tree view through the Items property of the tree view.


TTreeNodes properties

TTreeNodes	Alphabetically	Legend

In TTreeNodes

Count

Handle

Item

Owner


TTreeNodes properties

TTreeNodes	By object	Legend

Count

Handle

Item

Owner


TTreeNodes::Count

TTreeNodes	See also 	Example

Indicates the number of nodes maintained by the TTreeNodes object.

__property int Count = {read=GetCount, nodefault};

Description

Use Count to determine the number of tree nodes in the tree view that owns the tree nodes object. Count provides an upper bound when iterating through the entries in the Item property array.


TTreeNodes::Handle

TTreeNodes	See also

Contains the window handle of the tree view control that owns the tree nodes object.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Use Handle to obtain the handle of the tree view that owns the tree nodes object.


TTreeNodes::Item

TTreeNodes	See also

Lists all tree nodes managed by the TTreeNodes object.

__property TTreeNode* Item[int Index] = {read=GetNodeFromIndex};

Description

Use Item to access to a node by its position in the tree view. The first node has an index of 0, the second an index of 1, and so on.


TTreeNodes::Owner

TTreeNodes	See also

Specifies the tree view control that uses the tree nodes object to implement its Items property.

__property TCustomTreeView* Owner = {read=FOwner};

Description

Use the Owner property to access the tree view control that displays the nodes maintained by the TTreeNodes object.


TTreeNodes methods

TTreeNodes	Alphabetically

In TTreeNodes

~TTreeNodes

Add

AddChild

AddChildFirst

AddChildObject

AddChildObjectFirst

AddFirst

AddObject

AddObjectFirst

Assign

BeginUpdate

Clear

Delete

EndUpdate

GetFirstNode

GetNode

Insert

InsertObject

TTreeNodes

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TTreeNodes methods

TTreeNodes	By object

~TTreeNodes

Add

AddChild

AddChildFirst

AddChildObject

AddChildObjectFirst

AddFirst

AddObject

AddObjectFirst

Assign

BeginUpdate

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

Delete

Dispatch

EndUpdate

FieldAddress

Free

FreeInstance

GetFirstNode

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetNode

InheritsFrom

InitInstance

Insert

InsertObject

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TTreeNodes


TTreeNodes.Add

TTreeNodes	See also 	Example

Adds a new tree node to a tree view control.

TTreeNode* __fastcall Add(TTreeNode* Node, const System::AnsiString S);

Description

The node is added as the last sibling of the Node parameter. The S parameter specifies the Text property of the new node. Add returns the node that has been added. If the tree view is sorted, Add inserts the node in the correct sort order position rather than as the last child of the Node parameter’s parent.


TTreeNodes::AddChild

TTreeNodes	See also 	Example

Adds a new tree node to a tree view.

TTreeNode* __fastcall AddChild(TTreeNode* Node, const System::AnsiString S);

Description

The node is added as a child of the node specified by the Node parameter. It is added to the end of Node's list of child nodes. The S parameter specifies the Text property of the new node. AddChild returns the node that has been added. If the tree view is sorted, AddChild inserts the node in the correct sort order position, rather than as the last child of the Node parameter.


TTreeNodes::AddChildFirst

TTreeNodes	See also

Adds a new tree node to a tree view.

TTreeNode* __fastcall AddChildFirst(TTreeNode* Node, const System::AnsiString S);

Description

Use AddChildFirst to insert a node as the first child of the node specified by the Node parameter. The S parameter specifies the Text property of the new node. Nodes that appear after the added node are moved down one row and reindexed with valid Index values. AddChildFirst returns the node that has been added.


TTreeNodes::AddChildObject

TTreeNodes	See also 	Example

Adds a new tree node containing data to a tree view.

TTreeNode* __fastcall AddChildObject(TTreeNode* Node, const System::AnsiString S, void * Ptr);

Description

The node is added as the last child of the node specified by the Node parameter. The S parameter specifies the Text property of the new node. The Ptr parameter specifies the Data property value of the new node. AddChildObject returns the node that has been added.

Note:	The memory referenced by Ptr is not freed when the tree nodes object is freed.


TTreeNodes::AddChildObjectFirst

TTreeNodes	See also 	Example

Adds a new tree node containing data to a tree view.

TTreeNode* __fastcall AddChildObjectFirst(TTreeNode* Node, const System::AnsiString S, void * Ptr);

Description

The node is added as the first child of the node specified by the Node parameter. Nodes that appear after the added node are moved down one row and reindexed with valid Index values. The S parameter specifies the Text property of the new node. The Ptr parameter specifies the Data property value of the new node. AddChildObjectFirst returns the node that has been added.

Note:	The memory referenced by Ptr is not freed when the tree nodes object is freed.


TTreeNodes::AddFirst

TTreeNodes	See also

Adds a new tree node to a tree view.

TTreeNode* __fastcall AddFirst(TTreeNode* Node, const System::AnsiString S);

Description

The node is added as the first sibling of the node specified by the Node parameter. Nodes that appear after the added node are moved down one row and reindexed with valid Index values. The S parameter specifies the Text property of the new node. AddFirst returns the node that has been added.


TTreeNodes::AddObject

TTreeNodes	See also 	Example

Adds a new node containing data to a tree view.

TTreeNode* __fastcall AddObject(TTreeNode* Node, const System::AnsiString S, void * Ptr);

Description

The node is added as the last sibling of the node specified by the Node parameter. The S parameter specifies the Text property of the new node. The Ptr parameter specifies the Data property value of the new node. AddObject returns the node that has been added.

Note:	The memory referenced by Ptr is not freed when the tree nodes object is freed.


TTreeNodes::AddObjectFirst

TTreeNodes	See also

Adds a new node containing data to a tree view.

TTreeNode* __fastcall AddObjectFirst(TTreeNode* Node, const System::AnsiString S, void * Ptr);

Description

The node is added first to the list to which the node specified by the Node parameter belongs. nodes that appear after the added node are moved down one row and reindexed with valid Index values. The S parameter specifies the Text property of the new node. The Ptr parameter specifies the Data property value of the new node. AddObjectFirst returns the node that has been added.


TTreeNodes::Assign

TTreeNodes	See also

Discards any current property information and replaces it with the information from the Source.

virtual void __fastcall Assign(Classes::TPersistent* Source);

Description

Use Assign to copy information from one tree nodes object to another. If Source is any other type of object, Assign calls its parent class's method, which copies properties from any object that can copy to a TTreeNodes object in its AssignTo method.


TTreeNodes::BeginUpdate

TTreeNodes	See also

Prevents the updating of the tree view until the EndUpdate method is called.

void __fastcall BeginUpdate(void);

Description

BeginUpdate prevents the screen from being repainted when new nodes are added, deleted, or inserted. Tree nodes affected by the changes will have invalid Index values until EndUpdate is called.

Use BeginUpdate to prevent screen repaints and to speed processing time while adding nodes to the tree view.

Note:	Calls to BeginUpdate are cumulative; for every call to BeginUpdate there must be a corresponding call to EndUpdate.


TTreeNodes::Clear

TTreeNodes	See also

Deletes all tree nodes contained from the list managed by TTreeNodes.

void __fastcall Clear(void);

Description

Use the Clear method to remove all the nodes of a tree view.


TTreeNodes::TTreeNodes

TTreeNodes	See also

Creates an instance of a TTreeNodes object

__fastcall TTreeNodes(TCustomTreeView* AOwner);

Description

Call TTreeNodes indirectly using the new keyword to instantiate a TTreeNodes object at runtime. The TTreeNodes object used by TTreeView is created automatically from the constructor of the tree view object.

After calling the parent object’s constructor, TTreeNodes sets the Owner property of the tree nodes object to the value of the AOwner parameter.


TTreeNodes::Delete

TTreeNodes	See also 	Example

Removes a node from the tree view.

void __fastcall Delete(TTreeNode* Node);

Description

Delete removes a tree node in the tree view specified by the Node paramter.


TTreeNodes::~TTreeNodes

TTreeNodes	See also

Destroys an instance of TTreeNodes.

__fastcall virtual ~TTreeNodes(void);

Description

Do not call ~TTreeNodes directly in an application. The tree view that owns the TTreeNodes object destroys the tree nodes object by calling delete.


TTreeNodes::EndUpdate

TTreeNodes	See also

Re-enables screen repainting and node reindexing that was turned off with the BeginUpdate method.

void __fastcall EndUpdate(void);

Description

Use the EndUpdate method to enable screen updating after BeginUpdate has been called. Calls to BeginUpdate are cumulative, so calling EndUpdate will only update the tree view if every other call to BeginUpdate has already been matched by a call to EndUpdate.


TTreeNodes::GetFirstNode

TTreeNodes	See also 	Example

Returns the first tree node in the tree view.

TTreeNode* __fastcall GetFirstNode(void);

Description

Use the GetFirstNode method to retrieve the first node in the tree view. GetFirstNode returns the value of Item[0].


TTreeNodes::GetNode

TTreeNodes	See also

Returns the tree node given the ItemId of the tree node.

TTreeNode* __fastcall GetNode(HTREEITEM ItemId);

Description

ItemId is a handle to the node in the tree view.


TTreeNodes::Insert

TTreeNodes	See also

Inserts a tree node into the tree view after the node specified by the Node parameter.

TTreeNode* __fastcall Insert(TTreeNode* Node, const System::AnsiString S);

Description

Call Insert to add a new sibling to the Node parameter, immediately following Node. The S parameter specifies the Text property of the new node. Insert returns the new node.


TTreeNodes::InsertObject

TTreeNodes	See also

Inserts a tree node containing data into the tree view after the node specified by the Node parameter.

TTreeNode* __fastcall InsertObject(TTreeNode* Node, const System::AnsiString S, void * Ptr);

Description

Call InsertObject to add a new sibling to the Node parameter, immediately following Node. The S parameter specifies the Text property of the new node and the Ptr parameter specifies the Data property of the new node. InsertObject returns the new node.

Note:	The memory referenced by Ptr is not freed when the tree nodes object is freed.


Accessibility

Read-only


Hierarchy

TObject

TPersistent


 TTreeView

Hierarchy	Properties	Methods	Events	See also

TTreeView represents a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk.

Unit

comctrls

Description

Use TTreeView to add an expanding and contracting outline to a form. Each node in a tree view control consists of a label and a number of optional bitmapped images. Each node can have a list of subnodes associated with it. By clicking on a node, the user can expand or collapse the associated list of subnodes. This control can be seen as the left pane of the Database Explorer.


TTreeView properties

TTreeView	Alphabetically	Legend

Derived from TCustomTreeView

BorderStyle

DragMode

DropTarget

HideSelection

Images

Indent

Items

ReadOnly

RightClickSelect

Selected

ShowButtons

ShowLines

ShowRoot

SortType

StateImages

TopItem

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

Handle

HelpContext

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

Color

ControlState

ControlStyle

Cursor

DragCursor

Enabled

Font

Height

Hint

Left

Name

Parent

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TTreeView properties

TTreeView	By object	Legend

Align

BorderStyle

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

Color

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DesignInfo

DragCursor

DragMode

DropTarget

Enabled

Font

Handle

Height

HelpContext

HideSelection

Hint

Images

Indent

Items

Left

Name

Owner

Parent

ParentColor

ParentCtl3D

ParentFont

ParentShowHint

ParentWindow

PopupMenu

ReadOnly

RightClickSelect

Selected

ShowButtons

ShowHint

Showing

ShowLines

ShowRoot

SortType

StateImages

TabOrder

TabStop

Tag

Top

TopItem

VCLComObject

Visible

Width

WindowProc


TTreeView events

TTreeView	Alphabetically	Legend

Derived from TCustomTreeView

OnChange

OnChanging

OnCollapsed

OnCollapsing

OnCompare

OnDeletion

OnEdited

OnEditing

OnExpanded

OnExpanding

OnGetImageIndex

OnGetSelectedIndex

Derived from TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp

Derived from TControl

OnClick

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TTreeView events

TTreeView	By object	Legend

OnChange

OnChanging

OnClick

OnCollapsed

OnCollapsing

OnCompare

OnDblClick

OnDeletion

OnDragDrop

OnDragOver

OnEdited

OnEditing

OnEndDrag

OnEnter

OnExit

OnExpanded

OnExpanding

OnGetImageIndex

OnGetSelectedIndex

OnKeyDown

OnKeyPress

OnKeyUp

OnMouseDown

OnMouseMove

OnMouseUp

OnStartDrag


TTreeView methods

TTreeView	Alphabetically

In TTreeView

~TTreeView

TTreeView

Derived from TCustomTreeView

AlphaSort

CustomSort

FullCollapse

FullExpand

GetHitTestInfoAt

GetNodeAt

IsEditing

LoadFromFile

LoadFromStream

SaveToFile

SaveToStream

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTreeView methods

TTreeView	By object

~TTreeView

AlphaSort

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CustomSort

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

FullCollapse

FullExpand

GetHitTestInfoAt

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetNodeAt

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

IsEditing

LoadFromFile

LoadFromStream

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

SaveToFile

SaveToStream

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TTreeView

Update

UpdateControlState


TTreeView::TTreeView

TTreeView	See also

Creates a new TTreeView object.

__fastcall virtual TTreeView(Classes::TComponent* AOwner) : Comctrls::TCustomTreeView(AOwner) { }

Description

Call TTreeView indirectly, using the new keyword, to create a tree view at runtime.

Pass a single component as a parameter to provide the TTreeView object with an owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the tree view in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TTreeView::~TTreeView

TTreeView

Frees the memory associated with the TTreeView object.

__fastcall virtual ~TTreeView(void) { }

Description

Do not call ~TTreeView directly. Instead, use the delete keyword on the object, which causes ~TTreeView to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomTreeView


TTypedComObjectFactory

Hierarchy	Properties	Methods

TTypedComObjectFactory is the type of the class factory object used to instantiate a TypedComObject class.

Unit

comobj

Description

TTypedComObjectFactory inherits support for the IUnknown, IClassFactory, and IClassFactory2 interfaces. TTypedComObjectFactory is used to instantiate the TTypedComObject class.


TTypedComObjectFactory properties

TTypedComObjectFactory	Alphabetically	Legend

In TTypedComObjectFactory

ClassInfo

Derived from TComObjectFactory

ClassID

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TTypedComObjectFactory properties

TTypedComObjectFactory	By object	Legend

ClassID

ClassInfo

ClassName

ComClass

ComServer

Description

ErrorIID

Instancing

LicString

ProgID

SupportsLicensing


TTypedComObjectFactory::ClassInfo

TTypedComObjectFactory

Specifies an interface reference that provides type information without having to load a type library.

__property _di_ITypeInfo ClassInfo = {read=FClassInfo};

Description

ClassInfo is of type ITypeInfo, which is an interface usually used for reading information about objects. Use ITypeInfo to extract information about the characteristics and capabilities of objects from type libraries.

Type information interfaces are intended to describe the parts of the application that can be called by outside clients, rather than those that might be used internally to build an application.

The ITypeInfo interface provides access to the following:

•	The set of function descriptions associated with the type; for interfaces, this contains the set of member functions in the interface.

•	The set of data member descriptions associated with the type; for structures, this contains the set of fields of the type.

•	The general attributes of the type, such as whether it describes a structure, an interface, and so on.

An ITypeInfo instance provides various information about a type, and is used in different ways. A compiler can use an ITypeInfo to compile references to members of the type. A type interface browser can use it to find information about each member of the type.

Note:	An IDispatch implementer can use it to provide automatic delegation of IDispatch calls to an interface.

Note:	A type library is a container for type descriptions. A type library contains descriptions of one or more objects, and is accessed through the ITypeLib interface. The ITypeLib interface provides access to information about the type description in a type library. The descriptions of individual objects are accessed through the ITypeInfo interface.


TTypedComObjectFactory methods

TTypedComObjectFactory	Alphabetically

In TTypedComObjectFactory

~TTypedComObjectFactory

GetInterfaceTypeInfo

TTypedComObjectFactory

UpdateRegistry

Derived from TComObjectFactory

CreateComObject

RegisterClassObject

Derived from TObject

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TTypedComObjectFactory methods

TTypedComObjectFactory	By object

~TTypedComObjectFactory

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateComObject

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetInterfaceTypeInfo

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

RegisterClassObject

SafeCallException

TTypedComObjectFactory

UpdateRegistry


TTypedComObjectFactory::TTypedComObjectFactory

TTypedComObjectFactory	See also

Instantiates a TTypedComObjectFactory object.

__fastcall TTypedComObjectFactory(TComServerObject* ComServer, System::TMetaClass* TypedComClass, const GUID &ClassID, TClassInstancing Instancing);

Description

TTypedComObjectFactory is used to instantiate a TTypedComObjectFactory. TTypedComObjectFactory is automatically called when the COM server that contains the class definition for a TTypedComObject is loaded. Class factories should be instantiated in the initialization section of the unit that includes their associated server.

TTypedComObjectFactory allocates memory for a TTypedComObjectFactory, and verifies that a type library exists and is available, before calling the parent object’s constructor. If the type library is not available, an EOleSysError exception is raised.


TTypedComObjectFactory::GetInterfaceTypeInfo

TTypedComObjectFactory

Retrieves the type information for the typed COM object created by the factory.

_di_ITypeInfo __fastcall GetInterfaceTypeInfo(int TypeFlags);

Description

GetInterfaceTypeInfo is called to retrieve type information on the TTypedComObject instances that are created by the factory.


TTypedComObjectFactory::UpdateRegistry

TTypedComObjectFactory	See also

Registers the typed COM object class.

virtual void __fastcall UpdateRegistry(bool Register);

Description

UpdateRegistry is called for EXEs when the EXE is run, and for DLLs or EXEs when the routines are called to specifically register or unregister the server.


TTypedComObjectFactory::~TTypedComObjectFactory

TTypedComObjectFactory

~TTypedComObjectFactory frees the memory associated with the TTypedComObjectFactory object. Do not call ~TTypedComObjectFactory directly. Instead, use the delete keyword on the object, which causes ~TTypedComObjectFactory to be invoked automatically.

__fastcall virtual ~TTypedComObjectFactory(void) { }


Accessibility

Read-only


Hierarchy

TObject

TComObjectFactory


TTypedComObject

Hierarchy	Properties	Methods

TTypedComObject supports the IProvideClassInfo interface and is the class type for COM objects that can provide the type information without requring a type library to be loaded.

Unit

comobj

Description

TTypedComObject supports the IProvideClassInfo interface which gives an object the ability to describe its interfaces and types when everything else about it, such as its class identifier (CLSID), is unknown. TTypedComObject requires a type library for the IProvideClassInfo interface. This class is designed to require a type library so that it can support dual interfaces, which are created by default in C++Builder.

IProvideClassInfo has a single method, GetClassInfo, which is implemented in TTypedComObject to provide access to the type information for the object’s CoClass entry in its type library. This means that if the TTypedComObject has a running instance, a client can query for the IProvideClassInfo interface and retrieve this information without having to load and navigate a type library to find the ITypeInfo pointer for the object’s CoClass.

Use TTypedComObject as a base class for objects that can conveniently provide type information without having to load a type library, such as an unknown object received through a drag-and-drop operation. The only objects that must implement IProvideClassInfo are those with custom events such as ActiveX controls.

Note

There is no support for type information in a particular language. Type information appropriate to the user’s international settings on the current machine is assumed to have been loaded.

Implemented methods of IProvideClassInfo

GetClassClassInfo.


TTypedComObject properties

TTypedComObject	Alphabetically	Legend

Derived from TComObject

Controller

Factory

RefCount


TTypedComObject properties

TTypedComObject	By object	Legend

Controller

Factory

RefCount


TTypedComObject methods

TTypedComObject	Alphabetically

In TTypedComObject

~TTypedComObject

TTypedComObject

Derived from TComObject

Initialize

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TTypedComObject methods

TTypedComObject	By object

~TTypedComObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

Initialize

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

ObjAddRef

ObjQueryInterface

ObjRelease

SafeCallException

TTypedComObject


TTypedComObject::TTypedComObject

TTypedComObject

TTypedComObject creates a new TTypedComObject object.

__fastcall TTypedComObject(void) : Comobj::TComObject() { }

__fastcall TTypedComObject(_di_IUnknown const Controller) : Comobj:: TComObject(Controller) { }

__fastcall TTypedComObject(TComObjectFactory* Factory, _di_IUnknown const Controller) : Comobj::TComObject(Factory, Controller) { }

For descriptions of the parameters, refer to the TComObject topic.


TTypedComObject::~TTypedComObject

TTypedComObject

~TTypedComObject frees the memory associated with the TTypedComObject object. Do not call ~TTypedComObject directly. Instead, use the delete keyword on the object, which causes ~TTypedComObject to be invoked automatically.

__fastcall virtual ~TTypedComObject(void) { }


Accessibility

Read-only


Hierarchy

TObject

TComObject


TTypedComObject example

TTypedComObject


EUnsupportedTypeError

Hierarchy	Properties	Methods	See also

EUnsupportedTypeError is the exception class for failures that occur when adding dimensions to the cache of a decision cube.

Unit

mxarrays

Description

EUnsupportedTypeError is thrown when an invalid field type is chosen as an active dimension in a decision cube. For example, making a dimension that corresponds to a BLOB field active throws an EUnsupportedTypeError.


EUnsupportedTypeError properties

EUnsupportedTypeError	Alphabetically

Derived from Exception

HelpContext

Message


EUnsupportedTypeError properties

EUnsupportedTypeError	By object

HelpContext

Message


EUnsupportedTypeError methods

EUnsupportedTypeError	Alphabetically

In EUnsupportedTypeError

~EUnsupportedTypeError

EUnsupportedTypeError

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EUnsupportedTypeError methods

EUnsupportedTypeError	By object

~EUnsupportedTypeError

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

EUnsupportedTypeError

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


EUnsupportedTypeError::EUnsupportedTypeError

EUnsupportedTypeError	See also

EUnsupportedTypeError creates a new EUnsupportedTypeError object.

__fastcall EUnsupportedTypeError(const System::AnsiString Msg) : Sysutils::Exception(Msg) { }

__fastcall EUnsupportedTypeError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Msg, Args, Args_Size) { }

__fastcall EUnsupportedTypeError(int Ident, Extended Dummy) : Sysutils::Exception(Ident, Dummy) { }

__fastcall EUnsupportedTypeError(int Ident, const System::TVarRec * Args, const int Args_Size) : Sysutils::Exception(Ident, Args, Args_Size) { }

__fastcall EUnsupportedTypeError(const System::AnsiString Msg, int AHelpContext) : Sysutils::Exception(Msg, AHelpContext) { }

__fastcall EUnsupportedTypeError(const System::AnsiString Msg, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Msg, Args, Args_Size, AHelpContext) { }

__fastcall EUnsupportedTypeError(int Ident, int AHelpContext) : Sysutils::Exception(Ident, AHelpContext) { }

__fastcall EUnsupportedTypeError(int Ident, const System::TVarRec * Args, const int Args_Size, int AHelpContext) : Sysutils::Exception(Ident, Args, Args_Size, AHelpContext) { }

Description

EUnsupportedTypeError instantiates an exception object with a simple message string. Use the throw keyword with the constructor. For example,

throw EUnsupportedType("My error message");

Msg is the string containing the runtime error message to display in the exception dialog box. Msg can be a hard-coded string, or can be a function call that returns a string.

Args is an array of constants containing values to format according to format specifiers in Msg, and insert into Msg.

Args_Size is the size of Args.

AHelpContext is an integer that specifies the context-sensitive Help ID for the exception.

Ident is the unique ID of the resource as specified in the RES file. If Ident is not a valid resource ID, the constructor creates an empty message string for the exception.


EUnsupportedTypeError::~EUnsupportedTypeError

EUnsupportedTypeError	See also

~EUnsupportedTypeError frees the memory associated with the EUnsupportedTypeError object.

__fastcall virtual ~EUnsupportedTypeError(void) { }

Description

Do not call ~EUnsupportedTypeError directly. Instead, use the delete keyword on the object, which causes ~EUnsupportedTypeError to be invoked automatically.


Hierarchy

TObject

Exception


EUnsupportedTypeError example

EUnsupportedTypeError


 TUpdateSQL

Hierarchy	Properties	Methods	See also

TUpdateSQL provides an object for updating read-only datasets when cached updates are enabled.

Unit

dbtables

Description

Use a TUpdateSQL object to provide SQL statements used to update read-only datasets represented by TQuery components when cached updates are enabled. A dataset is read-only either by design or circumstance. If a dataset is read-only by design, the application itself does not provide a user interface for updating data, but may institute a programmatic scheme behind the scenes. If a dataset is read-only by circumstance, it indicates that the Borland Database Engine (BDE) returned a read-only result set. This usually happens for queries made against multiple tables. Such queries are, by SQL-92 definitions, read-only.

TUpdateSQL provides a mechanism for circumventing what some developers consider an SQL-92 limitation. It enables a developer to provide INSERT, UPDATE, and DELETE statements for performing separate update queries on otherwise read-only result sets in such a manner that the separate update queries are transparent to the end user.

In practical application, a TUpdateSQL object is placed on a data module or form, and linked to a TQuery component through that component’s UpdateSQL property. If the UpdateSQL property points to a valid TUpdateSQL object, the SQL statements belonging to the update object are automatically applied when cached updates are applied.


TUpdateSQL properties

TUpdateSQL	Alphabetically	Legend

In TUpdateSQL

DataSet

DeleteSQL

InsertSQL

ModifySQL

Query

SQL

Derived from TComponent

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag


TUpdateSQL properties

TUpdateSQL	By object	Legend

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DataSet

DeleteSQL

DesignInfo

InsertSQL

ModifySQL

Name

Owner

Query

SQL

Tag


TUpdateSQL::DataSet

TUpdateSQL	See also

Identifies the dataset to which a TUpdateSQL component belongs.

__property TDataSet* DataSet = {read=FDataSet, write=SetDataSet};

Description

At design time, setting the dataset object’s UpdateObject property automatically sets the DataSet property of the specified TUpdateSQL object. An application should only need to set this property if it creates a new update component at run time.


TUpdateSQL::DeleteSQL

TUpdateSQL	See also

Specifies the SQL DELETE statement to use when applying a cached deletion of a record.

__property Classes::TStrings* DeleteSQL = {read=GetSQLIndex, write=SetSQLIndex, index=2};

Description

Set DeleteSQL to the SQL DELETE statement to use when applying a deletion to a record. Statements can be parameterized queries. To create a DELETE statement at design time, use the UpdateSQL editor to create statements, such as:

DELETE FROM "COUNTRY.DB"

WHERE Name = :OLD_Name

At run time, an application can write a statement directly to this property to set or change the DELETE statement.

Note:	As the example illustrates, DeleteSQL supports an extension to normal parameter binding. To retrieve the value of a field as it exists prior to application of cached updates, the field name with ‘OLD_’. This is especially useful when doing field comparisons in the WHERE clause of the statement.


TUpdateSQL::InsertSQL

TUpdateSQL	See also

Specifies the SQL INSERT statement to use when applying a cached insertion of a record.

__property Classes::TStrings* InsertSQL = {read=GetSQLIndex, write=SetSQLIndex, index=1};

Description

Set InsertSQL to the SQL INSERT statement to use when applying an insertion to a dataset. Statements can be parameterized queries. To create a INSERT statement at design time, use the UpdateSQL editor to create statements, such as:

INSERT INTO "COUNTRY.DB"

(Name, Capital, Continent)

VALUES (:Name, :Capital, :Continent)

WHERE :OLD_Name = “Rangoon”

At run time, an application can write a statement directly to this property to set or change the INSERT statement.

Note:	As the example illustrates, InsertSQL supports an extension to normal parameter binding. To retrieve the value of a field as it exists prior to application of cached updates, the field name with ‘OLD_’. This is especially useful when doing field comparisons in the WHERE clause of the statement.


TUpdateSQL::ModifySQL

TUpdateSQL	See also

Specifies the SQL UPDATE statement to use when applying an update to a record and cached updates is enabled.

__property Classes::TStrings* ModifySQL = {read=GetSQLIndex, write=SetSQLIndex, index=0};

Description

Set ModifySQL to the SQL UPDATE statement to use when applying an updated record to a dataset. Statements can be parameterized queries. To create a UPDATE statement at design time, use the UpdateSQL editor to create statements, such as:

UPDATE "COUNTRY.DB"

SET Name = :Name, Capital = :Capital, Continent = :Continent

WHERE Name = :OLD_Name

At run time, an application can write a statement directly to this property to set or change the UPDATE statement.

Note:	As the example illustrates, ModifySQL supports an extension to normal parameter binding. To retrieve the value of a field as it exists prior to application of cached updates, the field name with ‘OLD_’. This is especially useful when doing field comparisons in the WHERE clause of the statement.


TUpdateSQL::Query

TUpdateSQL	See also

Returns the query object used to perform a specified kind of update.

__property TQuery* Query[Db::TUpdateKind UpdateKind] = {read=GetQuery};

Description

Set Query to return the TQuery object used to perform a particular form of SQL update. UpdateKind specifies which query object to retrieve. UpdateKind can be one of the following:

Value	Meaning

ukModify	Return the query object used to execute UPDATE statements.

ukInsert	Return the query object used to execute INSERT statements.

ukDelete	Return the query object used to execute DELETE statements

Each query object executes a particular kind of SQL statement. The contents of the SQL statements executed by these objects can be accessed directly using the ModifySQL, InsertSQL, and DeleteSQL properties.

The main purpose of Query is to provide a a way for an application to set the properties for an update query object or to call the query object’s methods.

Note:	If a particular kind of update statement is not provided, then its corresponding query object is NULL. For example, if an application does not provide an SQL statement for the DeleteSQL property, then setting Query[ukDelete] returns NULL.


TUpdateSQL.SQL

TUpdateSQL	See also

Returns a specified SQL statement used when applying cached updates.

__property Classes::TStrings* SQL[Db::TUpdateKind UpdateKind] = {read=GetSQL, write=SetSQL};

Description

Returns the SQL statement in the ModifySQL, InsertSQL, or DeleteSQL property, depending on the setting of UpdateKind. UpdateKind can be any of the following:

Value	Meaning

ukModify	Return the SQL statement used to update records in the dataset

ukInsert	Return the SQL statement used to insert new records into the dataset

ukDelete	Return the SQL statement used to delete records in the dataset.


TUpdateSQL methods

TUpdateSQL	Alphabetically

In TUpdateSQL

~TUpdateSQL

Apply

ExecSQL

SetParams

TUpdateSQL

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TUpdateSQL methods

TUpdateSQL	By object

~TUpdateSQL

Apply

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DestroyComponents

Destroying

Dispatch

ExecSQL

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

SetParams

TUpdateSQL


TUpdateSQL::Apply

TUpdateSQL	See also

Sets the parameters for a specified SQL statement type, and executes the resulting statement.

virtual void __fastcall Apply(Db::TUpdateKind UpdateKind);

Description

Call Apply to set parameters for an SQL statement and execute it to update a record. UpdateKind indicates which SQL statement to bind and execute, and can be one of the following values:

Value	Meaning

ukModify	Bind and execute the SQL statement in the ModifySQL property

ukInsert	Bind and execute the SQL statement in the InsertSQL property

ukDelete	Bind and execute the SQL statement in the DeleteSQL property

Apply is primarily intended for manually executing update statements from an OnUpdateRecord event handler.

Note:	If an SQL statement does not contain parameters, it is more efficient to call ExecSQL instead of Apply.


TUpdateSQL::TUpdateSQL

TUpdateSQL	See also

Creates an instance of an update object.

__fastcall virtual TUpdateSQL(Classes::TComponent* AOwner);

Description

Call TUpdateSQL to instantiate an update object at run time. You do not need to call TUpdateSQL for update objects placed in a data module or form at design time. C++Builder automatically handles these objects.


TUpdateSQL::~TUpdateSQL

TUpdateSQL	See also

Frees an instance of an update object.

__fastcall virtual ~TUpdateSQL(void);

Description

Do not call ~TUpdateSQL directly in an application. Usually destruction of update objects is handled automatically by C++Builder. If an application creates its own instance of an update object, however, the application should call Free, which verifies that the update object is not already freed before calling ~TUpdateSQL.


TUpdateSQL::ExecSQL

TUpdateSQL	See also

Executes a specified type of SQL statement to perform an update for an otherwise read-only results set when cached updates is enabled.

void __fastcall ExecSQL(Db::TUpdateKind UpdateKind);

Description

Call ExecSQL to execute the SQL statement necessary for updating the records belonging to a read-only result set when cached updates is enabled. UpdateKind specifies the statement to execute, and can be one of the following values:

Value	Meaning

ukModify	Execute the SQL statement used to update records in the dataset

ukInsert	Execute the SQL statement used to insert new records into the dataset

ukDelete	Execute the SQL statement used to delete records in the dataset.

If the statement to execute contains any parameters, an application must call SetParams to bind the parameters before calling ExecSQL. To determine if a statement contains parameters, examine the appropriate ModifySQL, InsertSQL, or DeleteSQL property, depending on the statement type intended for execution.

Note:	To both bind parameters and execute a statement, call Apply.


TUpdateSQL::SetParams

TUpdateSQL	See also

Binds parameters in an SQL statement prior to statement execution.

void __fastcall SetParams(Db::TUpdateKind UpdateKind);

Description

Call SetParams to bind parameters in an SQL statement associated with the update object prior to executing the statement. UpdateKind indicates the type of statement for which to bind parameters, and can be one of the following values:

Value	Meaning

ukModify	Bind parameters for SQL statement used to update records

ukInsert	Bind parameters for the SQL statement used to insert new records

ukDelete	Bind parameters for the SQL statement used to delete records

Parameters are indicated in an SQL statement by a colon. Except for the leading colon in the parameter name, the parameter name must exactly match the name of an existing field name for the dataset.

Note:	Parameter names can be prefaced by the ‘OLD_’ indicator. If so, the old value of the field is used to perform the update instead of any updates in the cache.


Scope

Published

Accessibility

Read-only


Hierarchy

TObject

TPersistent

TComponent

TDataSetUpdateObject


 TUpDown

Hierarchy	Properties	Methods	Events	See also

TUpDown is a wrapper for a Windows up-down control.

Unit

comctrls

Description

Use TUpDown to add an up-down control to a form. Up-down controls consist of a pair of arrow buttons, such as the arrows that appear in a spin box. Up-down controls allow users to change the size of a numerical value by clicking on arrow buttons.


TUpDown properties

TUpDown	Alphabetically	Legend

Derived from TCustomUpDown

AlignButton

ArrowKeys

Associate

Increment

Max

Min

Orientation

Position

Thousands

Wrap

Derived from TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Handle

HelpContext

ParentWindow

Showing

TabOrder

TabStop

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TUpDown properties

TUpDown	By object	Legend

Align

AlignButton

ArrowKeys

Associate

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Cursor

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

Increment

Left

Max

Min

Name

Orientation

Owner

Parent

ParentShowHint

ParentWindow

PopupMenu

Position

ShowHint

Showing

TabOrder

TabStop

Tag

Thousands

Top

VCLComObject

Visible

Width

WindowProc

Wrap


TUpDown events

TUpDown	Alphabetically	Legend

Derived from TCustomUpDown

OnChanging

OnClick

Derived from TWinControl

OnEnter

OnExit

Derived from TControl

OnMouseDown

OnMouseMove

OnMouseUp


TUpDown events

TUpDown	By object	Legend

OnChanging

OnClick

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp


TUpDown methods

TUpDown	Alphabetically

In TUpDown

~TUpDown

TUpDown

Derived from TWinControl

Broadcast

CanFocus

ContainsControl

ControlAtPos

DisableAlign

EnableAlign

Focused

GetTabOrderList

HandleAllocated

HandleNeeded

InsertControl

Invalidate

PaintTo

Realign

RemoveControl

Repaint

ScaleBy

ScrollBy

SetBounds

SetFocus

Update

UpdateControlState

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TUpDown methods

TUpDown	By object

~TUpDown

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

DefaultHandler

DestroyComponents

Destroying

DisableAlign

Dispatch

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetTabOrderList

GetTextBuf

GetTextLen

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

MethodAddress

MethodName

NewInstance

PaintTo

Perform

Realign

Refresh

RemoveComponent

RemoveControl

Repaint

SafeCallException

ScaleBy

ScreenToClient

ScrollBy

SendToBack

SetBounds

SetFocus

SetTextBuf

Show

TUpDown

Update

UpdateControlState


TUpDown::TUpDown

TUpDown

Creates a new TUpDown object.

__fastcall virtual TUpDown(Classes::TComponent* AOwner) : Comctrls::TCustomUpDown(AOwner) { }

__fastcall TUpDown(HWND ParentWindow) : Comctrls::TCustomUpDown(ParentWindow) { }

Description

Call TUpDown indirectly, using the new keyword, to create a TUpDown object at runtime. TUpDown objects added to forms at design time are created automatically.

Pass a single Component as a parameter to provide the TUpDown object with an Owner that is responsible for freeing it. This is the most commonly used constructor syntax. Pass a window handle as a parameter to embed the TUpDown object in a non-VCL window. This syntax is used when the control is implemented as an ActiveX control that is embedded in a non-VCL window.


TUpDown::~TUpDown

TUpDown

Frees the memory associated with the TUpDown object.

__fastcall virtual ~TUpDown(void) { }

Description

Do not call ~TUpDown directly. Instead, use the delete keyword on the object, which causes ~TUpDown to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomUpDown


TVarBytesField

Hierarchy	Properties	Methods	Events	See also

TVarBytesField represents a variable-length untyped binary field in a dataset.

Unit

db

Description

A variable bytes field value is a set of bytes of variable size, with the actual length of the value stored in the first two bytes.

TVarBytesField differs from its immediate ancestor TBytesField only in the data type it represents. Except for the constructor and the DataSize property, all of the properties, methods, and events are the same as those of TBytesField, and provide functionality that is useful for managing unformatted binary data fields in a dataset.


TVarBytesField properties

TVarBytesField	Alphabetically	Legend

In TVarBytesField

DataSize

Derived from TBinaryField

AsString

AsVariant

Value

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TVarBytesField properties

TVarBytesField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TVarBytesField::DataSize

TVarBytesField	See also 	Example

Indicates the amount of memory needed to store the value of a variable bytes field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a variable bytes field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For variable bytes fields, DataSize is Size + 2. The unformatted data can take up to Size bytes, and the extra 2 bytes store the length of the unformatted data.


TVarBytesField events

TVarBytesField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TVarBytesField events

TVarBytesField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TVarBytesField methods

TVarBytesField	Alphabetically

In TVarBytesField

~TVarBytesField

TVarBytesField

Derived from TField

Assign

AssignValue

Clear

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TVarBytesField methods

TVarBytesField	By object

~TVarBytesField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TVarBytesField

Validate


TVarBytesField::TVarBytesField

TVarBytesField	See also

Creates an instance of TVarBytesField.

__fastcall virtual TVarBytesField(Classes::TComponent* AOwner);

Description

It is seldom necessary to call TVarBytesField directly, because a VarBytes field object is instantiated automatically for all variable bytes fields in a dataset. When creating a TVarBytesField, use the new keyword.

After calling the parent object’s constructor, TVarBytesField sets the DataType to ftVarBytes and initializes the Size property to 16.


TVarBytesField::~TVarBytesField

TVarBytesField

Frees the memory associated with the TVarBytesField object.

__fastcall virtual ~TVarBytesField(void) { }

Description

Do not call ~TVarBytesField directly. Instead, use the delete keyword on the object, which causes ~TVarBytesField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TBinaryField

TBytesField


TWebModule

Hierarchy	Properties	Methods	Events	See also

TWebModule is the automatically generated Web module for a Web server application.

Unit

httpapp

Description

When a new Web application is created, it automatically contains a Web module. The Web module serves as a repository for non-visual components such as TPageProducer, TSession, TTable, TDataSetTableProducer, etc. It also enables the Web server application to respond to HTTP request messages by passing the request and response objects to the appropriate action items. An application can have only one Web module.

The TWebModule object manages a collection of action items which know how to respond to HTTP request messages. View, add and delete the action items managed by the Web module using the Action editor which is opened by double clicking on the TWebModule icon.

If a data module already exists which contains many of the non-visual components and business rules for the application, the Web module can be replaced by that data module. Simply delete the Web module, add the new data module in its place, and add a TWebDispatcher object to the new data module.

Note:	See the WebServ demo for an example of how to use TWebModule.


TWebModule properties

TWebModule	Alphabetically	Legend

Derived from TCustomWebDispatcher

Action

Actions

AfterDispatch

BeforeDispatch

Request

Response

Derived from TDataModule

DesignOffset

DesignSize

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TWebModule properties

TWebModule	By object	Legend

Action

Actions

AfterDispatch

BeforeDispatch

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

DesignOffset

DesignSize

Name

Owner

Request

Response

Tag

VCLComObject


TWebModule events

TWebModule	Alphabetically	Legend

Derived from TDataModule

OnCreate

OnDestroy


TWebModule events

TWebModule	By object	Legend

OnCreate

OnDestroy


TWebModule methods

TWebModule	Alphabetically

In TWebModule

~TWebModule

TWebModule

Derived from TCustomWebDispatcher

ActionByName

Derived from TDataModule

CreateNew

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TWebModule methods

TWebModule	By object

~TWebModule

ActionByName

Assign

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CreateNew

DefaultHandler

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

Free

FreeInstance

FreeNotification

FreeOnRelease

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

MethodAddress

MethodName

NewInstance

RemoveComponent

SafeCallException

TWebModule


TWebModule::TWebModule

TWebModule	See also

Creates an instance of TWebModule.

__fastcall virtual TWebModule(Classes::TComponent* AOwner);

__fastcall TWebModule(Classes::TComponent* AOwner, int Dummy) : Httpapp::TCustomWebDispatcher(AOwner, Dummy) { }

Description

Do not call the TWebModule method for TWebModule directly. The Web module is created automatically when a Web application project is created at design time. Every time a Web server application is run in response to an HTTP request message, a new TWebModule is created based on the Web module that was created at design time.

TWebModule generates an OnCreate event, so that Web applications can initialize the Web module before the new HTTP request message is processed.


TWebModule::~TWebModule

TWebModule

Frees the memory associated with the TWebModule object.

__fastcall virtual ~TWebModule(void) { }

Description

Do not call ~TWebModule directly. Instead, use the delete keyword on the object, which causes ~TWebModule to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TDataModule

TCustomWebDispatcher


TWinControl

Hierarchy	Properties	Methods	Events	See also

TWinControl is the base class for all windowed controls.

Unit

controls

Description

Windowed controls are controls that

•	Can receive focus while the application is running.

Other controls may display data, but the user can use the keyboard to interact with a control only if the control is a windowed control.

•	Can contain other controls.

A control that contains other controls is a parent. Only a windowed control can be a parent of one or more other child controls.

•	Have a window handle.

A window handle is the identifier provided by Windows for a window. Windowed controls can represent standard control windows provided by the Windows operating environment, or custom windows defined by the application.

Newly created components are seldom derived directly from TWinControl. Base most new controls on TCustomControl, which provides a canvas and handles paint messages, or on any of several more specialized controls, such as TButtonControl, TCustomComboBox, TCustomEdit, or TCustomListBox.


TWinControl properties

TWinControl	Alphabetically	Legend

In TWinControl

Brush

ClientOrigin

ClientRect

ControlCount

Controls

Ctl3D

DefWndProc

Handle

HelpContext

ImeMode

ImeName

ParentCtl3D

ParentWindow

Showing

TabOrder

TabStop

WindowHandle

Derived from TControl

Align

BoundsRect

ClientHeight

ClientWidth

ControlState

ControlStyle

Cursor

Enabled

Height

Hint

Left

Name

Parent

ShowHint

Top

Visible

Width

WindowProc

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Owner

Tag

VCLComObject


TWinControl properties

TWinControl	By object	Legend

Align

BoundsRect

Brush

ClientHeight

ClientOrigin

ClientRect

ClientWidth

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ControlCount

Controls

ControlState

ControlStyle

Ctl3D

Cursor

DefWndProc

DesignInfo

Enabled

Handle

Height

HelpContext

Hint

ImeMode

ImeName

Left

Name

Owner

Parent

ParentCtl3D

ParentWindow

ShowHint

Showing

TabOrder

TabStop

Tag

Top

VCLComObject

Visible

Width

WindowHandle

WindowProc


TWinControl::Brush

TWinControl	See also

Determines the color and pattern used for painting the background of the control.

__property Graphics::TBrush* Brush = {read=FBrush};

Description

Read the Brush property to determine the style and color of the control’s background. Brush is a read-only property, because a windowed control owns a single Brush object to handle the painting of its background. The attributes of the brush can be changed, however, by using the Color and Style properties of the TBrush object. Further, all of the attributes of the brush can be changed to match those of another brush, by using the Assign method of the TBrush object.


TWinControl::ClientOrigin

TWinControl	See also

Indicates the screen coordinates (in pixels) of the top left corner of the client area of the control.

__property tagPOINT ClientOrigin = {read=GetClientOrigin};

Description

Read ClientOrigin to discover where the top-left corner of the control is on the screen. ClientOrigin returns X and Y coordinates in a record of type tagPOINT. The tagPOINT type defines a pixel location onscreen, with the origin in the top left corner of the control. X specifies the horizontal coordinate of the point, Y specifies the vertical coordinate.


TWinControl::ClientRect

TWinControl	See also 	Example

Indicates the size (in pixels) of a control’s client area.

__property Windows::TRect ClientRect = {read=GetClientRect};

Description

Read ClientRect to learn the size of the client area of a control. ClientRect returns a rectangle defining the client area of the control. It is equivalent to Rect(0, 0, ClientWidth, ClientHeight).


TWinControl::ControlCount

TWinControl	See also 	Example

Indicates the number of controls that are children of the windowed control.

__property int ControlCount = {read=GetControlCount, nodefault};

Description

Use ControlCount when iterating over all the children of this control. The children of the control are listed in the Controls property array.

Note:	The value of ControlCount is always 1 greater than the highest Controls index, because the first Controls index is 0.


TWinControl::Controls

TWinControl	See also 	Example

Lists all children of the windowed control.

__property TControl* Controls[int Index] = {read=GetControl};

Description

Controls is an array of all the child controls of the windowed control. All of the child controls of the windowed control list the windowed control as their Parent property. The Controls property is convenient for referring to the children of a control by number rather than name. For example, Controls may be used to iterate over all the children of the windowed control.

Don't confuse the Controls property with the Components property. The Controls property lists all the controls that are child windows of the control, while the Components property lists all components that it owns. All components put on a form are owned by the form, and therefore, they appear in the form's Components property list, even when they are child windows of a control on the form.

Controls is a read-only property. To add or delete a child control, use the InsertControl or RemoveControl methods. To move a child control from one parent to another, set the Parent of the child control, as that will handle both the RemoveControl from the original parent and the InsertControl to the new parent.


TWinControl::Ctl3D

TWinControl	See also	Example

Determines whether a control has a three-dimensional (3-D) or two-dimensional look.

__property bool Ctl3D = {read=FCtl3D, write=SetCtl3D, stored=IsCtl3DStored, nodefault};

Description

Use Ctl3D to control the appearance of the control. If Ctl3D is true, the control has a beveled appearance. If Ctl3D is false, the control appears flat. The default value of Ctl3D is true.

If a control's ParentCtl3D property is true, then changes in the Ctl3D property of the control's parent automatically changes the Ctl3D property of the control. When assigning a value directly to a control's Ctl3D property, the control's ParentCtl3D property is automatically set to false.

Note:	For Ctl3D to work with radio buttons, check boxes, and any of the common dialog boxes on Windows NT 3::51, CTL3D32.DLL must be installed in the System32 directory. Neither Windows 95 nor NT 4::0 require CTL3D32.DLL.


TWinControl::DefWndProc

TWinControl	See also

Specifies the default window procedure for the windowed control.

__property void * DefWndProc = {read=FDefWndProc, write=FDefWndProc};

Description

Use the Windows API function CallWindowProc with DefWndProc to invoke the standard Windows message handling for a window message. Use DefWndProc instead of the WndProc method to avoid any message processing introduced by the WndProc method.

DefWndProc fills the role for windowed controls that DefaultHandler fills for all objects. The DefaultHandler for TWinControl uses DefWndProc to pass messages to Windows for processing.

For windowed controls, DefWndProc is initially set to the window procedure of the window class specified in the Params parameter in the CreateParams method. Change DefWndProc to subclass the window class of a windowed control.


TWinControl::Handle

TWinControl	See also 	Example

Provides access to the window handle of the control.

__property HWND Handle = {read=GetHandle, nodefault};

Description

Use the Handle when making Windows API function calls that requires a window handle.

If a window handle for the control doesn’t exist, the Handle property creates one by calling the HandleNeeded method when your application reads the Handle property value. Therefore, do not use the Handle property during component creation or streaming.


TWinControl::HelpContext

TWinControl	See also

Provides a context number for use in calling context-sensitive online Help.

typedef int THelpContext;

__property Classes::THelpContext HelpContext = {read=FHelpContext, write=FHelpContext, default=0};

Description

Assign a value to HelpContext to determine which help screen appears when the user presses F1 to request help.

Each screen in the Help system should have a unique context number. When a control is selected in the application, pressing F1 displays a Help screen. Which Help screen appears depends on the value of the HelpContext property.

If HelpContext is zero, then the control inherits the help context of its parent control. For example, if a button with a HelpContext of zero is contained in a form with a non-zero help context and F1 is pressed, the context screen for the form will be shown.


TWinControl::ImeMode

TWinControl	See also

Determines the behavior of the input method editor (IME).

enum TImeMode { imDisable, imClose, imOpen, imDontCare, imSAlpha, imAlpha, imHira, imSKata, imKata, imChinese, imSHanguel, imHanguel };

__property TImeMode ImeMode = {read=FImeMode, write=FImeMode, default=3};

Description

Set ImeMode to configure the way an IME processes user keystrokes. An IME is a front-end input processor for Asian language characters. The IME hooks all keyboard input, converts it to Asian characters in a conversion window, and sends the converted characters or strings on to the C++Builder application.

ImeMode allows a control to influence the type of conversion performed by the IME so that it is appropriate for the input expected by the control. For example, a control that only accepts numeric input might specify an ImeMode of imClose, as no conversion is necessary for numeric input.

ImeMode can have one of the following values:

Value	Meaning

imDisable	Shut down the IME. imDisable has no effect on Chinese, Taiwanese, or Korean IMEs.

imClose	Close the IME conversion window, but leave the IME running in the background. The IME can be re-activated by a hot key combination.

imOpen	Open the IME conversion window. The conversion mode is the last conversion mode used by the IME.

imDontCare	Launch the IME if it is disabled. The conversion mode is the last conversion mode used by the IME.

imSAlpha	Open the IME conversion window and set the conversion mode to accept single-width Roman alphabet input.

imAlpha	Open the IME conversion window and set the conversion mode to accept double-width Roman alphabet input.

imHira	Open the IME conversion window and set the conversion mode to double-width Hiragana. imHira is only available for Japanese IMEs.

imSKata	Open the IME conversion window and set the conversion mode to single-width Katakana (Hankaku Katakana). imSKata is only available for Japanese IMEs.

imKata	Open the IME conversion window and set the conversion mode to double-width Katakana (Zenkaku Katakana). imKata is only available for Japanese IMEs.

imChinese	Open the IME conversion window and set the conversion mode to double-width Chinese. imChinese is only available for Chinese IMEs.

imSHanguel	Open the IME conversion window and set the conversion mode to single-width Hanguel. imSHanguel is only available for Korean IMEs.

imHanguel	Open the IME conversion window and set the conversion mode to double-width Hanguel. imHanguel is only available for Korean IMEs.

Note:	The value of ImeMode only takes effect when the control receives focus. To change the value of ImeMode after the control has gotten input focus, call the SetIme method.


TWinControl::ImeName

TWinControl	See also

Specifies the input method editor (IME) to use for converting keyboard input to asian language characters.

__property System::AnsiString ImeName = {read=FImeName, write=FImeName};

Description

Set ImeName to specify which IME to use for converting keystrokes. An IME is a front-end input processor for Asian language characters. The IME hooks all keyboard input, converts it to Asian characters in a conversion window, and sends the converted characters or strings on to the C++Builder application.

ImeName must specify one of the IMEs that has been installed through the Windows control panel. The property inspector provides a drop-down list of all currently installed IMEs on the system. At runtime, applications can obtain a list of currently installed IMEs from the global Screen variable.

If ImeName specifies an unavailable IME, the IME that was active when the application started is used instead. No exception is generated.

Note:	The value of ImeName only takes effect when the control receives focus. To change the value of ImeName after the control has gotten input focus, call the SetIme method.


TWinControl::ParentCtl3D

TWinControl	See also	Example

Determines where a component looks to determine if it should appear three dimensional.

__property bool ParentCtl3D = {read=FParentCtl3D, write=SetParentCtl3D, default=1};

Description

Use ParentCtl3D to ensure that all the components on a form have a uniform appearance. For example, to make all components on a form appear beveled, set the form's Ctl3D property to true and each control's ParentCtl3D property to true. Not only will all components have a beveled appearance, but to change to a uniform two-dimensional appearance, you only have to change the Ctl3D property of the form and all the components will appear flat.

If ParentCtl3D is true, the component uses the value of its parent component's Ctl3D property. If ParentCtl3D is false, the control uses the value of its own Ctl3D property. The default value is true.

To specify either a 2D or 3D appearance for a particular component, set Ctl3D to true (for 3D) or false (for 2D). When setting the Ctl3D property of a control, ParentCtl3D automatically gets set to false.


TWinControl::ParentWindow

TWinControl	See also

Contains the window handle of a non-VCL parent window that contains the control.

__property HWND ParentWindow = {read=FParentWindow, write=SetParentWindow, nodefault};

Description

Set ParentWindow to host a windowed control in an non-VCL parent window. Setting ParentWindow moves the control so that it is contained in the specified window. For example, TActiveXControl objects use ParentWindow to insert a control in an ActiveX container window. ParentWindow is set automatically when a parent window is passed to the control’s constructor.

Use ParentWindow with windowed controls that are packaged in a DLL so that they may be used by a VB, OWL or MFC application.

A TWinControl object can have either a Parent property or a ParentWindow property, but not both. If the Parent property of a control is not NULL, the value of ParentWindow is ignored.


TWinControl::Showing

TWinControl	See also

Specifies whether the control is currently showing on the screen.

__property bool Showing = {read=FShowing, nodefault};

Description

Use the Showing property to determine if the user can see the control on the screen, assuming that another control is not obstructing it from view.

If the Visible properties of a component and all the parents in its parent hierarchy are true, Showing is true. If one of the parents containing the component has a Visible property value of false, Showing is false.


TWinControl::TabOrder

TWinControl	See also	Example

Indicates the position of the control in its parent's tab order.

__property TTabOrder TabOrder = {read=GetTabOrder, write=SetTabOrder, default=-1};

Description

TabOrder is the order in which child windows are visited when the user presses the Tab key. The control with the TabOrder value of 0 is the control that has the focus when the form first appears.

Initially, the tab order is always the order in which the controls were added to the form. The first control added to the form has a TabOrder value of 0, the second is 1, the third is 2, and so on. Change this by changing the TabOrder property. A control with a TabOrder of -1 is outside the tab order, and cannot be reached by pressing the Tab key.

Each control has a unique tab-order value within its parent. If you change the TabOrder property value of one control to be the same as the value of a second control, the TabOrder value for all the other controls changes. For example, suppose a control is sixth in the tab order. If you change the control's TabOrder property value to 3 (making the control fourth in the tab order), the control that was originally fourth in the tab order now becomes fifth, and the control that was fifth becomes sixth.

Assigning TabOrder a value greater than the number of controls contained in the parent control moves the control to the end of the tab order. The control does not take on the assigned value of TabOrder, but instead is given the number that assures the control is the last in the tab order.

Note:	TabOrder is meaningful only if the TabStop property is true and if the control has a parent. The TabOrder property of a form is not used unless the form assigns another form to be its parent.


TWinControl::TabStop

TWinControl	See also	Example

Determines if the user can tab to a control.

__property bool TabStop = {read=FTabStop, write=SetTabStop, default=0};

Description

Use the TabStop to allow or disallow access to the control using the Tab key.

If TabStop is true, the control is in the tab order. If TabStop is false, the control is not in the tab order and the user can't press the Tab key to move to the control.

Note:	TabStop is not meaningful for a form unless the form assigns another form to be its parent.


TWinControl::WindowHandle

TWinControl	See also

Provides access to a window handle for the control.

__property HWND WindowHandle = {read=FHandle, write=FHandle, nodefault};

Description

The WindowHandle property provides access to the same window handle as the Handle property, but WindowHandle is protected, and therefore only accessible to code inside the control.

The advantage to using WindowHandle is that it can be written to, while the Handle property is read-only. WindowHandle is intended to be used when implementing methods that need to change the value of the control’s window handle. Unlike the Handle property, reading the value of WindowHandle doesn’t automatically create a valid handle. Reading WindowHandle can return a zero value.


TWinControl events

TWinControl	Alphabetically	Legend

In TWinControl

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp


TWinControl events

TWinControl	By object	Legend

OnEnter

OnExit

OnKeyDown

OnKeyPress

OnKeyUp


TWinControl::OnEnter

TWinControl	See also 	Example

Occurs when a control receives the input focus.

__property Classes::TNotifyEvent OnEnter = {read=FOnEnter, write=FOnEnter};

Description

Use the OnEnter event handler to cause any special processing to occur when a windowed component becomes active.

The OnEnter event does not occur when switching between forms or between another Windows application and the application that includes the windowed control.

When switching between controls in separate container controls such as the TPanel and the TGroupBox controls, an OnEnter event occurs for the container before the OnEnter event of the contained control.

Similarly, an OnExit event of the container occurs after the OnExit event of the control in a container when focus moves to another control outside the container.

For example, consider a form with an OK button and a group box that contains three radio buttons, where focus is currently on the OK button. When the user clicks one of the radio buttons, an OnExit event of the button occurs, followed by an OnEnter event on the group box, and finally an OnEnter event on the radio button that was clicked. If the user then clicks on the OK button, an OnExit event for the radio button occurs followed by an OnExit event for the group box, and then the button’s OnEnter event occurs.


TWinControl::OnExit

TWinControl	See also 	Example

Occurs when the input focus shifts away from one control to another.

__property Classes::TNotifyEvent OnExit = {read=FOnExit, write=FOnExit};

Description

Use the OnExit event handler to provide special processing when the control ceases to be active.

The OnExit event does not occur when switching between forms or between another Windows application and your application.

When switching between controls in separate container controls such as the TPanel and the TGroupBox controls, an OnExit event occurs for the control inside the container before the OnExit event of the container.

Similarly, an OnEnter event of the container occurs before the OnEnter event of the control in a container when focus moves to a control inside a container.

For example, consider a form with an OK button and a group box that contains three radio buttons, where focus is currently on the OK button. When the user clicks one of the radio buttons, an OnExit event of the button occurs, followed by an OnEnter event on the group box, and finally an OnEnter event on the radio button that was clicked. If the user then clicks on the OK button, an OnExit event for the radio button occurs followed by an OnExit event for the group box, and then the button’s OnEnter event occurs.

Note:	The value of the ActiveControl property updates before the OnExit event occurs.


TWinControl::OnKeyDown

TWinControl	See also 	Example

Occurs when a user presses any key while the control has focus.

typedef void __fastcall (__closure *TKeyEvent)(System::TObject* Sender, Word &Key, Classes::TShiftState Shift);

__property TKeyEvent OnKeyDown = {read=FOnKeyDown, write=FOnKeyDown};

Description

Use the OnKeyDown event handler to specify special processing to occur when a key is pressed. The OnKeyDown handler can respond to all keyboard keys, including function keys and keys combined with the Shift, Alt, and Ctrl keys, and pressed mouse buttons.

The TKeyEvent type points to a method that handles keyboard events. The Key parameter is the key on the keyboard. For non-alphanumeric keys, use WinAPI virtual key codes to determine the key pressed. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

The Shift parameter indicates whether the Shift, Alt, or Ctrl keys are combined with the keystroke.  It can include zero or more of the following values:

State	Meaning

ssShift	The Shift key is held down.

ssAlt	The Alt key is held down.

ssCtrl	The Ctrl key is held down.


TWinControl::OnKeyPress

TWinControl	See also 	Example

Occurs when a user presses a single character key.

typedef void __fastcall (__closure *TKeyPressEvent)(System::TObject* Sender, char &Key);

__property TKeyPressEvent OnKeyPress = {read=FOnKeyPress, write=FOnKeyPress};

Description

Use the OnKeyPress event handler to make something happen as a result of a single character key press.

The Key parameter in the OnKeyPress event handler is of type Char; therefore, the OnKeyPress event registers the ASCII character of the key pressed. Keys that don't correspond to an ASCII Char value (Shift or F1, for example) don't generate an OnKeyPress event. Key combinations (such as Shift+A), generate only one OnKeyPress event (for this example, Shift+A results in a Key value of “A” if Caps Lock is off). To respond to non-ASCII keys or key combinations, use the OnKeyDown or OnKeyUp event handlers.


TWinControl::OnKeyUp

TWinControl	See also 	Example

Occurs when the user releases a key that has been pressed.

typedef void __fastcall (__closure *TKeyEvent)(System::TObject* Sender, Word &Key, Classes::TShiftState Shift);

__property TKeyEvent OnKeyUp = {read=FOnKeyUp, write=FOnKeyUp};

Description

Use the OnKeyUp event handler to provide special processing that occurs when a key is released. The OnKeyUp handler can respond to all keyboard keys, including function keys and keys combined with the Shift, Alt, and Ctrl keys.

The TKeyEvent type points to a method that handles keyboard events. The Key parameter is the key on the keyboard. For non-alphanumeric keys, you must use WinAPI virtual key codes to determine the key pressed. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

The Shift parameter indicates whether the Shift, Alt, or Ctrl keys are combined with the keystroke.  It can include zero or more of the following values:

State	Meaning

ssShift	The Shift key is held down.

ssAlt	The Alt key is held down.

ssCtrl	The Ctrl key is held down.


TWinControl methods

TWinControl	Alphabetically	Legend

In TWinControl

~TWinControl

AlignControls

Broadcast

CanFocus

ChangeScale

ContainsControl

ControlAtPos

CreateHandle

CreateParams

CreateSubClass

CreateWindowHandle

CreateWnd

DefaultHandler

DestroyHandle

DestroyWindowHandle

DestroyWnd

DisableAlign

DoEnter

DoExit

DoKeyDown

DoKeyPress

DoKeyUp

EnableAlign

FindNextControl

FixupTabList

Focused

GetChildren

GetClientOrigin

GetClientRect

GetDeviceContext

GetParentHandle

GetTabOrderList

GetTopParentHandle

HandleAllocated

HandleNeeded

InsertControl

Invalidate

IsControlMouseMsg

KeyDown

KeyPress

KeyUp

MainWndProc

NotifyControls

PaintControls

PaintHandler

PaintTo

PaintWindow

PaletteChanged

ReadState

Realign

RecreateWnd

RemoveControl

Repaint

ResetIme

ResetImeComposition

ScaleBy

ScaleControls

ScrollBy

SelectFirst

SelectNext

SetBounds

SetChildOrder

SetFocus

SetIme

SetImeCompositionWindow

SetZOrder

ShowControl

TWinControl

Update

UpdateControlState

WndProc

Derived from TControl

BeginDrag

BringToFront

ClientToScreen

DragDrop

Dragging

EndDrag

GetTextBuf

GetTextLen

Hide

Perform

Refresh

ScreenToClient

SendToBack

SetTextBuf

Show

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

Assign

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TWinControl methods

TWinControl	By object	Legend

~TWinControl

AlignControls

Assign

BeginDrag

BringToFront

Broadcast

CanFocus

ChangeScale

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

ClientToScreen

ContainsControl

ControlAtPos

CreateHandle

CreateParams

CreateSubClass

CreateWindowHandle

CreateWnd

DefaultHandler

DestroyComponents

DestroyHandle

Destroying

DestroyWindowHandle

DestroyWnd

DisableAlign

Dispatch

DoEnter

DoExit

DoKeyDown

DoKeyPress

DoKeyUp

DragDrop

Dragging

EnableAlign

EndDrag

FieldAddress

FindComponent

FindNextControl

FixupTabList

Focused

Free

FreeInstance

FreeNotification

FreeOnRelease

GetChildren

GetClientOrigin

GetClientRect

GetDeviceContext

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

GetParentHandle

GetTabOrderList

GetTextBuf

GetTextLen

GetTopParentHandle

HandleAllocated

HandleNeeded

HasParent

Hide

InheritsFrom

InitInstance

InsertComponent

InsertControl

InstanceSize

Invalidate

IsControlMouseMsg

KeyDown

KeyPress

KeyUp

MainWndProc

MethodAddress

MethodName

NewInstance

NotifyControls

PaintControls

PaintHandler

PaintTo

PaintWindow

PaletteChanged

Perform

ReadState

Realign

RecreateWnd

Refresh

RemoveComponent

RemoveControl

Repaint

ResetIme

ResetImeComposition

SafeCallException

ScaleBy

ScaleControls

ScreenToClient

ScrollBy

SelectFirst

SelectNext

SendToBack

SetBounds

SetChildOrder

SetFocus

SetIme

SetImeCompositionWindow

SetTextBuf

SetZOrder

Show

ShowControl

TWinControl

Update

UpdateControlState

WndProc


TWinControl::AlignControls

TWinControl	See also

Aligns any controls for which the control is the parent within a specified area of the control.

virtual void __fastcall AlignControls(TControl* AControl, Windows::TRect &Rect);

Description

Use AlignControls to align all controls within an area of a form, panel, group box, scroll box, or any windowed control that contains several other controls. Specify the area in which to align the controls as the value of the Rect parameter.

AlignControls uses the Align property value for each child control to determine how to align it. The AControl parameter can be NULL. If you specify a control in AControl, that control takes precedence in alignment over other, similarly-aligned controls.


TWinControl::Broadcast

TWinControl	See also

Sends a message to each of the child controls of the windowed control.

void __fastcall Broadcast(void *Message);

Description

Use Broadcast when you want to send the same message to each of the child controls contained within the windowed control. Specify the message to be passed as the value of the Message parameter.


TWinControl::CanFocus

TWinControl	See also	Example

Indicates whether a control can receive focus.

bool __fastcall CanFocus(void);

Description

Call CanFocus to find out if the control can receive input from the user.

CanFocus returns true if both the control and its parent(s) have their Visible and Enabled properties set to true. If any of the Visible and Enabled properties of the control or the controls in which it is contained are not true, then CanFocus returns false. Override the CanFocus method to provide further restrictions to when the control can receive focus in descendent objects.


TWinControl::ChangeScale

TWinControl	See also

Resizes and repositions the control, rescaling the children of the control before the control itself is rescaled.

DYNAMIC void __fastcall ChangeScale(int M, int D);

Description

ChangeScale can be used to change the scale of a form and all its controls for a different screen resolution or font size. Because ChangeScale modifies the control’s Top, Left, Width, and Height properties, it changes the position of the control and its children as well as their size.

The M parameter is the multiplier and the D parameter is the divisor. For example, to change a control and its children to be 75% of their original sizes, specify the value of M as 75, and the value of D as 100 (75/100). Alternately, specify the value of M as 3, and the value of D as 4 (3/4). Both fractions are equal and result in the controls being scaled by the same amount, 75%.

To make the control and its children 33% larger than their previous sizes, specify the value of M as 133, and the value of D as 100 (133/100), or obtain the same results by specifying the value of M as 4, and the value of D as 3 (4/3).

Note:	Because control sizes and coordinates are integers, scaling them by the M/D ratio incurs some degree of roundoff error. Calling ChangeScale repeatedly can mean that at some point the control disappears (when the roundoff errors make the control smaller), or at some point it creeps off the form (when the roundoff errors move the location of control). If rescaling a form repeatedly, destroy and reload the form after several rescalings to eliminate the accumulating roundoff error.


TWinControl::ContainsControl

TWinControl	See also	Example

Indicates whether a specified control exists within the control.

bool __fastcall ContainsControl(TControl* Control);

Description

Use ContainsControl to find out if the a particular control exists within this control. ContainsControl returns true if the specified value of the Control parameter is a child control of the windowed control. The Control parameter need not be an immediate child (in the Controls property), but may be contained in a child of the windowed control, or in a child of a child of the windowed control, for indefinitely many levels deep.

If the method returns false, the specified control is not within the control.


TWinControl::ControlAtPos

TWinControl	See also

Returns the child control located at a specified position within the control.

TControl* __fastcall ControlAtPos(const tagPOINT &Pos, bool AllowDisabled);

Description

Use ControlAtPos when you want to know which child control is at the specified location within the control. ControlAtPos will return an immediate child of the windowed control; that is, one of the entries of the Controls property, that has the windowed control for its Parent property.

Specify the position in client coordinates as the value of the Pos parameter. Pos can be anywhere within the boundaries of the child control, not just the upper left corner.

If there is no control at the specified position, ControlAtPos returns NULL. The AllowDisabled parameter determines whether the search for controls includes disabled controls.


TWinControl::TWinControl

TWinControl	See also

Creates an instance of TWinControl.

__fastcall virtual TWinControl(Classes::TComponent* AOwner);

__fastcall TWinControl(HWND ParentWindow);

Description

Call TWinControl indirectly, using the new keyword, to construct and initialize a new windowed control.

Pass in a component as an argument to insert the newly-constructed control into its owner, as specified by the AOwner parameter. TWinControl inserts the control in the owner by calling the owner's InsertComponent method. This is the most comonly used constructor syntax.

Pass in a window handle as an argument to embed the windowed control in a non-VCL parent window. TActiveXControl objects use this syntax to create an ActiveX control as a child of the host application’s client site window. When using this syntax, the application must explicitly delete the windowed control to free its memory.

After calling the parent class’s constructor, TWinControl

•	Creates and initializes the Brush.

•	Initializes the ParentCtl3D property to true.

•	Sets the TabOrder property to -1.


TWinControl::TWinControl
TWinControl::CreateHandle

TWinControl	See also

Generates a window for the control if it does not already exist.

virtual void __fastcall CreateHandle(void);

Description

CreateHandle calls the CreateWnd method to create the window if the control has a parent. The Window handle for this window becomes the value of the Handle property.

CreateHandle creates or locates the parent control’s window before it creates a window for the control itself.

Note:	If the Parent property is NULL, CreateHandle throws an exception.


TWinControl::TWinControl
TWinControl::CreateParams

TWinControl	See also

Initializes a window-creation parameter record passed in the Params parameter.

virtual void __fastcall CreateParams(TCreateParams &Params);

Description

The CreateWnd method calls CreateParams to initialize the parameters it passes to CreateWindowHandle. Override CreateParams to customize the way a control creates its Windows representation. When overriding CreateParams, always call the parent class’s method first to set the default values, then make any desired adjustments.

Specify the parameter record as the value of the Params parameter. The TCreateParams type is a data structure holding information needed when telling Windows to create a window handle. The fields of a TCreateParams record become the parameters to a call to the CreateWindowEx API function.

TWinControl implements CreateParams by setting all the fields of Params to generic base values. A number of the standard controls override CreateParams to change one or more of the default values in Params.


TWinControl::TWinControl
TWinControl::CreateSubClass

TWinControl	See also

Creates a windowed control derived from an existing Windows window class.

void __fastcall CreateSubClass(TCreateParams &Params, char * ControlClassName);

Description

Call CreateSubClass in the CreateParams method of a subclassed control, after calling the parent class’s CreateParams. Specify the parameter record as the value of the Params parameter. CreateSubClass allows VCL controls to create registered Windows controls.


TWinControl::TWinControl
TWinControl::CreateWindowHandle

TWinControl	See also

Creates a Windows control to represent the control.

virtual void __fastcall CreateWindowHandle(const TCreateParams &Params);

Description

The CreateWnd method calls CreateWindowHandle to create the window for a control. CreateWindowHandle creates the window by calling the CreateWindowEx API function, passing parameters from the record passed in the Params parameter. Once the window is created, its handle is available as the Handle property.


TWinControl::TWinControl
TWinControl::CreateWnd

TWinControl	See also

Creates the window used by the windowed-control component.

virtual void __fastcall CreateWnd(void);

Description

CreateWnd is called automatically when the windowed control is first created or when the window must be destroyed and recreated to reflect property changes. Override CreateWnd to pass additional initialization messages to the window when it is first created.

CreateWnd first calls the CreateParams method to initialize the window-creation parameters, then calls CreateWindowHandle to create the window handle for the control. CreateWnd adjusts the size of the newly-created window and then sets the control's font by calling the Perform method, passing the WM_SETFONT message.


TWinControl::DefaultHandler

TWinControl	See also

Provides message handling for all messages that the control does not fully process itself.

virtual void __fastcall DefaultHandler(void *Message);

Description

Override DefaultHandler to change the default message handling for the control. The Message parameter can be cast to a TMessage type, to obtain the WParam, LParam, and Result of the message. If the Result of the message is non-zero, the message has already been handled. Set the Result field to a non-zero value to prevent further processing of the message by the parent class’s method.

TWinControl overrides TControl::DefaultHandler to handle messages for all its descendant types. DefaultHandler passes any otherwise-unhandled messages to the control's window procedure using the CallWindowProc API function.


TWinControl::~TWinControl

TWinControl	See also

Destroys an instance of TWinControl.

__fastcall virtual ~TWinControl(void);

Description

Do not call ~TWinControl directly in an application. Instead, use the delete keyword.


TWinControl::~TWinControl
TWinControl::DestroyHandle

TWinControl	See also

Destroys the windowed control's window without destroying the control.

void __fastcall DestroyHandle(void);

Description

Call DestroyHandle to dispose of the window, but leave the control intact. The control can later recreate the window if needed. DestroyHandle is the converse operation to CreateHandle. Applications should call the high-level CreateHandle and DestroyHandle methods, rather than the lower-level methods of CreateWnd and DestroyWnd, whenever possible.

If the control has windowed controls as child controls, DestroyHandle calls each of their DestroyHandle methods before calling DestroyWnd to destroy its own handle.


TWinControl::~TWinControl
TWinControl::DestroyWindowHandle

TWinControl	See also

Destroys the window created in the CreateWindowHandle method.

virtual void __fastcall DestroyWindowHandle(void);

Description

Call DestroyWindowHandle to dispose of the window for the control.

TWinControl's Destroy method calls DestroyWindowHandle to destroy any window handle associated with a windowed control before destroying the object. The DestroyWnd method also calls DestroyWindowHandle.


TWinControl::~TWinControl
TWinControl::DestroyWnd

TWinControl	See also

Destroys the control's window.

virtual void __fastcall DestroyWnd(void);

Description

DestroyWnd is called when the control needs to replace its window.  For example, changing properties that are implemented by window parameter settings require the control to be destroyed and then recreated using the CreateWnd method.

Before the window is destroyed, DestroyWnd saves a copy of the control's text in memory, frees any device contexts, and finally calls DestroyWindowHandle.  When the window is recreated, the stored copy of the control’s text is assigned to the new window.


TWinControl::DisableAlign

TWinControl	See also

Disables the realigning of controls within the windowed control.

void __fastcall DisableAlign(void);

Description

Call DisableAlign to temporarily prevent child controls from realigning. For example, while performing multiple manipulations of controls, such as reading from a form file or scaling, performance improves if child controls are not realigned until all manipulations are complete. Each call to DisableAlign must be followed by a corresponding call to EnableAlign.

DisableAlign increments a reference count that EnableAlign later decrements. When the reference count reaches zero, EnableAlign performs any needed realignments.


TWinControl::DoEnter

TWinControl	See also

Generates an OnEnter event.

DYNAMIC void __fastcall DoEnter(void);

Description

The DoEnter method does nothing except call any event handler attached to the OnEnter event. Override DoEnter to provide other responses in addition to the event-handler call or to suppress the OnEnter event.


TWinControl::DoExit

TWinControl	See also

Generates an OnExit event.

DYNAMIC void __fastcall DoExit(void);

Description

The DoExit method does nothing except call any event handler attached to the OnExit event. Override DoExit to provide other responses in addition to the event-handler call or to suppress the OnExit event.


TWinControl::DoKeyDown

TWinControl	See also

Performs some preprocessing before generating an OnKeyDown event.

struct TWMKey

{

  Cardinal Msg;

  Word CharCode;

  Word Unused;

  int KeyData;

  int Result;

} ;

bool __fastcall DoKeyDown(Messages::TWMKey &Message);

Description

The return value from DoKeyDown determines if the control should continue processing key-down messages passed in the Message parameter. A return value of true indicates that the key-down occurrence has been handled completely, and no further processing is needed. A return value of false indicates that the application should continue passing the key-down message through the parent class’s processing.

DoKeyDown checks whether the KeyPreview property of the parent form is true; and if so, allows the form to preemptively process key-down messages before they are handled by the windowed control. If the form does not handle the message, DoKeyDown translates the message parameters into the appropriate types and calls KeyDown, which in turn calls the OnKeyDown event handler, if any.

The TWMKey type is the message record for all Windows keyboard messages.


TWinControl::DoKeyPress

TWinControl	See also

Performs some preprocessing before generating an OnKeyPress event.

struct TWMKey

{

  Cardinal Msg;

  Word CharCode;

  Word Unused;

  int KeyData;

  int Result;

} ;

bool __fastcall DoKeyPress(Messages::TWMKey &Message);

Description

The return value from DoKeyPress determines whether the control should continue processing the key-press message passed in the Message parameter. A return value of true indicates that the key-press occurrence has been handled completely, and no further processing is needed. A return value of false indicates that the application should continue passing the key-press message through the parent class’s processing.

DoKeyPress checks whether the KeyPreview property of the parent form is true, and if so, allows the form to preemptively process key-press messages before they are handled by the windowed control::If the form does not handle the message, DoKeyPress translates the message parameters into the appropriate types and calls KeyPress, which in turn calls the OnKeyPress event handler, if any.

The TWMKey type is the message record for all Windows keyboard messages.


TWinControl::DoKeyUp

TWinControl	See also

Performs some preprocessing before generating an OnKeyUp event.

struct TWMKey

{

  Cardinal Msg;

  Word CharCode;

  Word Unused;

  int KeyData;

  int Result;

} ;

bool __fastcall DoKeyUp(Messages::TWMKey &Message);

Description

The return value from DoKeyUp determines whether the control should continue processing the key-up message passed in the Message parameter. A return value of true indicates that the key-up occurrence has been handled completely, and no further processing is needed. A return value of false indicates that the application should continue passing the key-up message through the parent class’s processing.

DoKeyUp checks whether the KeyPreview property of the parent form is true, and if so, allows the form to preemptively process key-up messages before they are handled by the windowed control. If the form does not handle the message, DoKeyUp translates the message parameters into the appropriate types and calls KeyUp, which in turn calls the OnKeyUp event handler, if any.

The TWMKey type is the message record for all Windows keyboard messages.


TWinControl::EnableAlign

TWinControl	See also

Decrements the reference count incremented by the DisableAlign method, eventually realigning the child controls of the windowed control.

void __fastcall EnableAlign(void);

Description

Call EnableAlign to allow child controls within the control to realign again after they were prevented from realigning by a call to DisableAlign.

Each time the DisableAlign method is called, it increments a reference count. Each time EnableAlign is called, it decrements the same reference count. When the reference count reaches zero, EnableAlign calls the Realign method to perform any pending realignments.

Be sure to pair each call to DisableAlign with a call to EnableAlign. If an exception could be raised after the call to DisableAlign, use a try ::. finally statement to ensure that the corresponding call to EnableAlign is executed.


TWinControl::FindNextControl

TWinControl	See also

Returns the windowed control's next child control in the tab order after the specified control.

TWinControl* __fastcall FindNextControl(TWinControl* CurControl, bool GoForward, bool CheckTabStop, bool CheckParent);

Description

Call FindNextControl to find the next child control in the tab order after CurControl. If CurControl is not a child of the windowed control, FindNextControl returns the first child control in the tab order.

The GoForward parameter controls the direction of the search. If GoForward is true, FindNextControl searches forward through the child controls in tab order. If Go Forward is false, FindNextControl searches backward through the controls.

The CheckTabStop and CheckParent parameters control whether FindNextControl performs certain checks on the controls it finds. If CheckTabStop is true, the returned control must have its TabStop property set to true. If CheckParent is true, the returned control's Parent property must indicate the windowed control.

FindNextControl calls the GetTabOrderList method to build its list of possible "next" controls.


TWinControl::FixupTabList

TWinControl	See also

Sorts the child controls of this control by their tab order.

void __fastcall FixupTabList(void);

Description

Applications should not call FixupTabList directly. C++Builder uses this method in its implementation of the ReadState method to initialize the tab order list based on the TabOrder properties of the child controls being read from the stream.


TWinControl::Focused

TWinControl	See also 	Example

Determines whether the windowed control has input focus.

bool __fastcall Focused(void);

Description

Use the Focused method to see if the control is the active control. When Focused is true, the control has the focus. If Focused is false, the user cannot interact with the control.


TWinControl::GetChildren

TWinControl	See also

Calls a specified method for each child of the windowed control.

typedef void __fastcall (__closure *TGetChildProc)(TComponent* Child);

DYNAMIC void __fastcall GetChildren(Classes::TGetChildProc &Proc, Classes::TComponent* Root);

Description

GetChildren is called by the VCL streaming system that loads and saves components. Applications seldom need to call this routine. Some specialized controls may override GetChildren to limit which child controls are saved with the control. When overriding GetChildren, call the procedure passed as the Proc parameter for every child control that should be saved.


TWinControl::GetClientOrigin

TWinControl	See also

Returns the value of the ClientOrigin property.

virtual tagPOINT __fastcall GetClientOrigin();

Description

GetClientOrigin is the protected implementation of the ClientOrigin property.

GetClientOrigin returns a point indicating the position of the top-left corner of the control in screen coordinates. GetClientOrigin calls the Windows API function ClientToScreen to return the position of top-left corner of the windowed control on the screen in screen coordinates.


TWinControl::GetClientRect

TWinControl	See also

Returns the value of the ClientRect property.

virtual Windows::TRect __fastcall GetClientRect();

Description

GetClientRect is the protected implementation of the ClientRect property. GetClientRect returns a rectangle with the rectangle’s Top and Left fields set to zero, and its Bottom and Right fields set to the control's ClientHeight and ClientWidth, respectively. GetClientRect calls the Windows API function GetClientRect.


TWinControl::GetDeviceContext

TWinControl	See also

Provides access to a device context for the control.

virtual HDC __fastcall GetDeviceContext(HWND &WindowHandle);

Description

Call GetDeviceContext to obtain a handle to a device context for the control.

GetDeviceContext calls the Windows API function GetDC, passing the windowed control's Handle property. It returns the window’s Handle property in the WindowHandle parameter and the HDC as the return value. If the call is unsuccessful, the EOutOfResources exception is thrown.


TWinControl::GetParentHandle

TWinControl	See also

Returns the window handle for the window of the control’s parent.

HWND __fastcall GetParentHandle(void);

Description

Use the handle returned by GetParentHandle as a parameter to Windows API function calls that need the window handle for the parent window of the control. If the Parent property is not NULL, GetParentHandle returns the Handle property of the parent control. If the Parent property is NULL, GetParentHandle returns the value of ParentWindow.


TWinControl::GetTabOrderList

TWinControl	See also

Builds a list of controls in tab order.

DYNAMIC void __fastcall GetTabOrderList(Classes::TList* List);

Description

Call GetTabOrderList to construct a list of child controls in tab order.

GetTabOrderList iterates through the windowed control's internal tab-order list, adding each of the controls to List, including any controls contained in those controls. The result is a list of all the controls and their owned controls, in tab order.

The FindNextControl method calls GetTabOrderList to build a complete list of the controls that FindNextControl uses to locate the next control in the tab order.


TWinControl::GetTopParentHandle

TWinControl	See also

Returns the window handle of the first window not associated with a VCL control that contains the windowed control.

HWND __fastcall GetTopParentHandle(void);

Description

Use GetTopParentHandle to access the handle of the window that is hosting the windowed control. GetTopParentHandle walks up the containers of the windowed control until it finds a control whose Parent property is NULL. If that topmost parent is contained in a non-VCL window (its ParentWindow is nonzero), GetTopParentHandle returns the non-VCL window. If the windowed control is not contained in a non-VCL window, GetTopParentHandle returns the windowed control’s own window handle.


TWinControl::HandleAllocated

TWinControl	See also	Example

Reports whether a window handle exists for the control.

bool __fastcall HandleAllocated(void);

Description

Query HandleAllocated to find out if the control’s window has been generated.

If a window exists, HandleAllocated returns true. If no window exists, HandleAllocated returns false. Testing the Handle property of a control directly causes the window to be created if it does not already exist. Call the HandleAllocated method to determine whether a window exists without creating one as a side effect.


TWinControl::HandleNeeded

TWinControl	See also	Example

Creates a window for the control if it doesn't already exist.

void __fastcall HandleNeeded(void);

Description

Call HandleNeeded to create a window for the control.

If no window exists, HandleNeeded calls the CreateHandle method for the parent of the control before it creates a window for this control.


TWinControl::InsertControl

TWinControl	See also 	Example

Inserts a control into the Controls array property of the windowed control.

void __fastcall InsertControl(TControl* AControl);

Description

Applications should not need to call InsertControl directly. Child controls are automatically inserted and removed when added or deleted at design time. At runtime, use the Parent property of the child control to insert it in the Controls array. If the child control is already the child of another windowed control, setting the Parent property ensures that the child is removed from the Controls of the original parent.

InsertControl makes the inserted control a child, and the containing control the parent. The AControl parameter is the child control that is inserted into the Controls array.


TWinControl::Invalidate

TWinControl	See also	Example

Tells Windows to repaint the control after other important Windows messages are handled.

virtual void __fastcall Invalidate(void);

Description

Use Invalidate when the entire control needs to be repainted. When more than one region within the control needs repainting, Invalidate will cause the entire window to be repainted in a single pass, avoiding flicker caused by redundant repaints. There is no performance penalty for calling Invalidate multiple times before the control is actually repainted.


TWinControl::IsControlMouseMsg

TWinControl	See also

Indicates whether a specified mouse message is directed to one of the windowed control’s child controls.

bool __fastcall IsControlMouseMsg(Messages::TWMMouse &Message);

Description

Call IsControlMouseMsg to find out if a mouse message is directed to one of the control’s child controls. Specify the mouse message as the value of the Message parameter.

Windows takes care of sending messages to windowed child controls, but for nonwindowed child controls, Windows sends the messages to the parent control, which must then determine which, if any, of its child controls should receive the message.

The WndProc method of a windowed control calls IsControlMouseMsg to process all mouse message sent to the windowed control.


TWinControl::KeyDown

TWinControl	See also

Generates an OnKeyDown event.

DYNAMIC void __fastcall KeyDown(Word &Key, Classes::TShiftState Shift);

Description

The KeyDown method in TWinControl does nothing except call any event handler attached to the OnKeyDown event. Override KeyDown to provide other responses in addition to the event-handler call.

The Key parameter is the key on the keyboard. For non-alphanumeric keys, you must use WinAPI virtual key codes to determine the key pressed. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

A windowed control calls KeyDown in response to a key-down message (WM_KEYDOWN) from Windows. The actual sequence is that the message goes to a private message handler that calls the DoKeyDown method. If DoKeyDown determines that the control should, in fact, process the character, it decodes the parameters of the key-down message and passes the key code and shift-key state to KeyDown in the Key and Shift parameters, respectively.

Either KeyDown or the OnKeyDown event handler it calls can suppress further processing of a key by setting the Key parameter to zero.

The Shift parameter indicates whether the Shift, Alt, or Ctrl keys are combined with the keystroke.  It can include zero or more of the following values:

State	Meaning

ssShift	The Shift key is held down.

ssAlt	The Alt key is held down.

ssCtrl	The Ctrl key is held down.


TWinControl::KeyPress

TWinControl	See also

Generates an OnKeyPress event.

DYNAMIC void __fastcall KeyPress(char &Key);

Description

The KeyPress method in TWinControl does nothing except call any event handler attached to the OnKeyPress event. Override KeyPress to provide other responses in addition to the event-handler call.

A windowed control calls KeyPress in response to a key-press message (WM_CHAR) from Windows. The actual sequence is that the message goes to a private message handler that calls the DoKeyPress method. If DoKeyPress determines that the control should, in fact, process the character, it decodes the parameters of the key-down message and passes the key code to KeyPress in the Key parameters, respectively.

Either KeyPress or the OnKeyPress event handler it calls can suppress further processing of a character by setting the Key parameter to zero.

Note:	The Key parameter is the character represented by the key that is pressed, not the Windows virtual key code.


TWinControl::KeyUp

TWinControl	See also

Generates an OnKeyUp event.

DYNAMIC void __fastcall KeyUp(Word &Key, Classes::TShiftState Shift);

Description

The KeyUp method calls the OnKeyUp event handler if it is assigned. Override KeyUp to provide other responses in addition to the event-handler call.

A windowed control calls KeyUp in response to a key-up message (WM_KEYUP) from Windows. The actual sequence followed when a key is released is as follows:

1	The DoKeyUp method determines whether the control should, in fact, process the character.

2	If the character should be processed, DoKeyUp decodes the parameters of the key-up message and passes the key code and shift-key state to KeyUp in the Key and Shift parameters, respectively.

3	Either KeyUp or the OnKeyUp event handler it calls can suppress further processing of a key by setting the Key parameter to zero.

The Key parameter is the key on the keyboard. For non-alphanumeric keys, use WinAPI virtual key codes to determine the key pressed. For more information, search for VkKeyScan and VkKeyScanEx in the Win32 Developer's Reference (WIN32.HLP).

The Shift parameter indicates whether the Shift, Alt, or Ctrl keys are combined with the keystroke.  It can include zero or more of the following values:

State	Meaning

ssShift	The Shift key is held down.

ssAlt	The Alt key is held down.

ssCtrl	The Ctrl key is held down.


TWinControl::MainWndProc

TWinControl	See also

Recieves Windows messages for the control.

void __fastcall MainWndProc(Messages::TMessage &Message);

Description

MainWndProc is the window procedure for the control that is associated with the control’s window when it is created. When Windows sends a message to the control’s window, MainWndProc receives it.

MainWndProc does not process or dispatch the messages itself, but rather calls the method specified by WindowProc to do that. MainWndProc provides an exception-handling block around WindowProc, ensuring that if any unhandled exceptions occur during the processing of a message, the application’s HandleException method will handle them.


TWinControl::NotifyControls

TWinControl	See also

Sends a message to all the child windows of the windowed control.

void __fastcall NotifyControls(Word Msg);

Description

The NotifyControls method sends a message with the message ID passed in the Msg parameter to all the controls in the windowed control's Controls array property. C++Builder uses NotifyControls to update all the controls in a form of such occurrences as changes in the parent color or font.

NotifyControls constructs a generic message record, filling its message ID field with the value of Msg and setting its parameter and result fields to zeros, then calls the Broadcast method to send the message to all the child controls.


TWinControl::PaintControls

TWinControl	See also

Paints each of the child controls in a windowed control using the specified device context.

void __fastcall PaintControls(HDC DC, TControl* First);

Description

Call PaintControls to paint all the child controls of this control. Pass the device context as the value of the DC parameter. The First parameter indicates the starting point in the windowed control's child-control list to paint. If First is NULL or does not indicate one of the child controls, PaintControls paints all the child controls.

The Repaint method calls PaintControls for the control's parent, passing the control in First to repaint the control and any controls it might intersect. PaintHandler also calls PaintControls after calling PaintWindow.


TWinControl::PaintHandler

TWinControl	See also

Responds to WM_PAINT messages.

void __fastcall PaintHandler(Messages::TWMPaint &Message);

Description

PaintHandler is called automatically when the control receives a WM_PAINT message. It calls the BeginPaint and EndPaint API functions, and between them paints the control's background by calling PaintWindow and any child controls by calling PaintControls.


TWinControl::PaintTo

TWinControl	See also 	Example

Draws the windowed control to a device context.

void __fastcall PaintTo(HDC DC, int X, int Y);

Description

Call PaintTo to draw the control on a device context. Specify the device context as the value of the DC parameter and specify the X and Y coordinates on the device context where the top-left corner of the windowed control is to be drawn. PaintTo first erases the background of the device context and then paints the control.

PaintTo is useful for drawing an image of the control into a bitmap DC.


TWinControl::PaintWindow

TWinControl	See also

Renders the image of a windowed control.

virtual void __fastcall PaintWindow(HDC DC);

Description

Call PaintWindow to repaint the control. PaintWindow sends a WM_PAINT message to the windowed control's DefaultHandler method, setting the message record's WParam field to the value passed in DC and the other parameter and result fields to zeros.


TWinControl::PaletteChanged

TWinControl	See also

Responds to changes in the system's palette by realizing the control's palette and the palette for each child control.

DYNAMIC bool __fastcall PaletteChanged(bool Foreground);

Description

PaletteChanged is called automatically when the Windows system palette changes. TWinControl responds to these notifications by trying to realize the windowed control’s palette, if any, into the current device context, and then passing on the PaletteChanged notification to each of the child controls in turn. If the change in the system palette causes the actual value of the control’s palette to change, PaletteChanged will invalidate the control so that it can repaint with the new palette.

Windows paints the active window with a foreground palette, while other windows are forced to use background palettes. Background palettes are approximate matches to the colors specified by the control’s logical palette, given the limitations imposed by implementing the foreground palette. Windows only allows a single foreground palette.

PaletteChanged allows the control to obtain a new realization of its palette when the system palette changes. When ForeGround is true, the form has been activated and the control is specifying the new foreground palette. When ForeGround is false, another application or form has changed the foreground palette, and controls that are sensitive to the available palette should realize new background palettes to best match their logical palettes.

If the control does not have a logical palette to be realized into the current device context, GetPalette will return a handle of 0, and PaletteChanged will not try to realize a palette for the windowed control. Instead, it simply passes the notification on to the child controls. If the windowed control or any of its child controls realize a palette into the current device context in response to PaletteChanged, this method returns true.

Override PaletteChanged to change the way in which controls are given an opportunity to realize a new palette when the windows system palette changes. For example, override PaletteChanged to change the order in which child controls realize their palettes, giving a particular control the foreground palette when the form is activated, or to pass palette change notification to custom controls implemented outside of C++Builder, such as in DLLs. Override GetPalette instead to affect whether the windowed control actually has a palette to realize, or to change the value of the control’s logical palette.

Note:	PaletteChanged is called only when the run-time video mode requires palette support, such as for 256 color mode, but not 16 million color mode.


TWinControl::ReadState

TWinControl	See also

Prepares the control for having its properties assigned values from a stream.

virtual void __fastcall ReadState(Classes::TReader* Reader);

Description

Override ReadState to change the preparations the control makes as it readies itself to have its property values assigned from a stream. For example, the windowed control might destroy temporary internal data structures or objects before new instances are loaded from the stream. Be sure to include a call to the parent class’s method when overriding ReadState.

ReadState disables control alignment until all the child controls have been read from the stream, calls the parent class’s ReadState method, and re-enables the alignment of all the controls. The method then builds the tab order list of controls and synchronizes its Ctl3D property and its visibility with that of its parent control.


TWinControl::Realign

TWinControl	See also

Forces the windowed control to realign the controls within it.

void __fastcall Realign(void);

Description

The EnableAlign method calls Realign when its reference count reaches zero.

If all of the child controls of this control have their Align properties set to alNone, Realign has no effect.


TWinControl::RecreateWnd

TWinControl	See also

Destroys the window associated with a windowed control so that another can be generated to reflect the control’s current state.

void __fastcall RecreateWnd(void);

Description

Call RecreateWnd to recreate the control. RecreateWnd destroys the window used by the control, setting the window handle to NULL. The next time the window handle is needed, such as when the control needs to be painted, a new window is created that reflect’s the properties of the control.

Windows does not reflect certain kinds of changes to a control without destroying the window and recreating it. For example, to reflect a change in the border style of an edit box, the window for the control must be recreated.


TWinControl::RemoveControl

TWinControl	See also 	Example

Removes a specified control from the Controls array.

void __fastcall RemoveControl(TControl* AControl);

Description

Applications should not need to call RemoveControl directly. Child controls are automatically inserted and removed when added or deleted at design time. At runtime, use the Parent property of the child control to remove it from the Controls array.

RemoveControl removes a child control from the Controls property. The result is that this control is no longer the parent of the child specified by the AControl parameter.


TWinControl::Repaint

TWinControl	See also

Repaints the windowed control’s image on the screen.

virtual void __fastcall Repaint(void);

Description

Call Repaint to repaint the control.

The Repaint method calls the Invalidate method and then the Update method to repaint the control.


TWinControl::ResetIme

TWinControl	See also

Restores the input method editor (IME) that was active when the application started.

void __fastcall ResetIme(void);

Description

For controls that specify the ImeName property, call ResetIme to revert to the IME that was active when the application started. If the IME was deactivated by setting the IMEMode property to imDisable, ResetIme restarts the default IME.

Applications cannot call ResetIme. ResetIme is called automatically when the control loses input focus. It is exposed as a protected method so that descendant objects can restore the default IME at other times.


TWinControl::ResetImeComposition

TWinControl	See also

Directs the composition window of the input method editor (IME) to perform a specific action.

bool __fastcall ResetImeComposition(int Action);

Description

Call ResetImeComposition to direct what the composition window does with the input typed by the user. The composition window is the window displayed by the IME that provides feedback to the user about what keystrokes have been typed, and how they are converted into asian characters.

The Action parameter indicates what the composition window should do with its current contents. Action can have one of the following values:

Value	Meaning

CPS_CANCEL	Clear the composition string and set the status to no composition string.

CPS_COMPLETE	Set the composition string as the result string.

CPS_CONVERT	Convert the composition string.

CPS_REVERT	Cancel the current composition string and revert to the unconverted string.

ResetImeComposition returns true if the composition window performs the requested action.


TWinControl::ScaleBy

TWinControl	See also	Example

Rescales a windowed control and any of its children to a percentage of their former size.

void __fastcall ScaleBy(int M, int D);

Description

Call ScaleBy to rescale the control and all its children. ScaleBy modifies the Height and Width properties of the controls, but it does not change the Top and Left properties; therefore, the size of the controls changes, but not the coordinates of the top-left corners of the controls.

The M and D parameters determine the percentage by which the control and its children are scaled. The M parameter is the multiplier and the D parameter is the divisor. For example, to change a control to be 75% of its original size, specify the value of M as 75, and the value of D as 100 (75/100). Alternately, obtain the same results by specifying the value of M as 3, and the value of D as 4 (3/4). Both fractions are equal and result in the control being scaled by the same amount, 75%.

To make the control 33% larger than its previous size, specify the value of M as 133, and the value of D as 100 (133/100), or specify the value of M as 4, and the value of D as 3 (4/3), as the fraction 133/100 is approximately equal to 4/3.

Note:	Because control sizes and coordinates are integers, scaling them by the M/D ratio incurs some degree of roundoff error. Calling ScaleBy repeatedly may mean that at some point the control disappears (when the roundoff errors make the control smaller). When rescaling controls repeatedly, consider destroying and reloading the form after several rescalings so that the coordinates are rescaled without most of the accumulating roundoff error.


TWinControl::ScaleControls

TWinControl	See also

Rescales the child controls of a windowed control without rescaling the control itself.

void __fastcall ScaleControls(int M, int D);

Description

Call ScaleControls to rescale only the children of the control, while leaving the control itself the same size.

ScaleControls calls the ChangeScale method of each child control, specifying the percentage to scale by through the M and D parameters. M is the multiplier and D is the divisor. For example, to change the child controls to be 75% of their original size, specify the value of M as 75, and the value of D as 100 (75/100). Alternately, specify the value of M as 3, and the value D as 4 (3/4). Both fractions are equal and result in the controls being scaled by the same amount, 75%.

Note:	Because control sizes and coordinates are integers, scaling them by the M/D ratio incurs some degree of roundoff error. Calling ScaleBy repeatedly means that at some point the control may disappear (when the roundoff errors make the control smaller), or creep off the form (when the roundoff errors move the location of control). When rescaling controls repeatedly, consider destroying and reloading the form after several rescalings so that the coordinates are rescaled without most of the accumulating roundoff error.


TWinControl::ScrollBy

TWinControl	See also	Example

Scrolls the contents of a windowed control.

void __fastcall ScrollBy(int DeltaX, int DeltaY);

Description

Call ScrollBy to scroll the contents within the control. While ScrollBy can be used for any windowed control, it makes the most sense to use it for descendents of TScrollingWinControl.

Applications seldom need to call the ScrollBy method unless they implement their own scrolling interface rather than relying on a scroll bar.

The DeltaX parameter is the change in pixels along the X axis. A positive DeltaX value scrolls the contents to the right; a negative value scrolls the contents to the left. The DeltaY parameter is the change in pixels along the Y axis. A positive DeltaY value scrolls the contents down; a negative value scrolls the contents up.


TWinControl::SelectFirst

TWinControl	See also

Locates the first child selectable control in the tab order within the windowed control.

void __fastcall SelectFirst(void);

Description

Call SelectFirst to find the first child that can be selected within the control’s tab order. SelectFirst calls the FindNextControl method, passing NULL as the current control. Once the first selectable control is found, SelectFirst makes the control the active control on the form.


TWinControl::SelectNext

TWinControl	See also

Moves the input focus from the current child control to the next one in the tab order.

void __fastcall SelectNext(TWinControl* CurControl, bool GoForward, bool CheckTabStop);

Description

Call SelectNext to find the next child control in the control’s tab order. Specify the current control from which to begin the search as the value of the CurControl parameter. The GoForward parameter controls the direction of the search. If GoForward is true, FindNextControl searches forward through the child controls in tab order. If GoForward is false, FindNextControl searches backward through the controls.

The CheckTabStop parameter controls whether the control SelectNext finds must be a tab stop. If CheckTabStop is true, the returned control must have its TabStop property set to true, or the search for the next control continues.

If SelectNext doesn’t locate an appropriate control (as defined by the GoForward and the CheckTabStop parameters), the focus remains with CurControl.


TWinControl::SetBounds

TWinControl	See also	Example

Sets the windowed control's boundary properties all at once.

virtual void __fastcall SetBounds(int ALeft, int ATop, int AWidth, int AHeight);

Description

Use SetBounds to change all of the control’s boundary properties at once. The same effect can be achieved by setting the Left, Top, Width, and Height properties separately. By setting all four properties at once, SetBounds ensures that the control will not repaint between changes

Specify the values for the Left, Top, Width, and Height properties as the value of the ALeft, ATop, AWidth, and AHeight parameters, respectively.


TWinControl::SetChildOrder

TWinControl	See also

Changes the order in which the child component appears in the list of child components returned by the GetChildren method.

DYNAMIC void __fastcall SetChildOrder(Classes::TComponent* Child, int Order);

Description

Use SetChildOrder when you want to change the order in which child objects are streamed in. Specify the child component whose order you want to change as the value of the Child parameter. Indicate the position you want the component to be in as the value of the Order parameter.

When SetChildOrder is called, items previously below the child's old position move up, and those below the new position move down.


TWinControl::SetFocus

TWinControl	See also 	Example

Gives the input focus to the control.

virtual void __fastcall SetFocus(void);

Description

Use SetFocus to change the focus to another control.


TWinControl::SetIme

TWinControl	See also

Activates an input method editor (IME) using the values specified by the ImeMode and ImeName properties.

void __fastcall SetIme(void);

Description

Applications cannot call SetIme. SetIme is called automatically when the control receives input focus. It is exposed as a protected method so that descendant objects can cause the ImeMode and ImeName properties to take effect at other times.


TWinControl::SetImeCompositionWindow

TWinControl	See also

Sets the position and font of the composition window.

bool __fastcall SetImeCompositionWindow(Graphics::TFont* Font, int XPos, int YPos);

Description

Call SetImeComposition to change the position or font of the composition window. The composition window is the window displayed by the input method editor (IME) that provides feedback to the user about what keystrokes have been typed, and how they are converted into asian characters.

The Font parameter describes the font that the composition window should use. Setting the Font parameter to NULL repositions the composition window without changing the font. XPos and YPos specify the desired global coordinates for the composition window.

SetImeCompositionWindow returns true if the font and position are successfully assigned.


TWinControl::SetZOrder

TWinControl	See also

Moves the control within the parent’s control list to either the top or bottom of the windowed controls; or, if the control has no parent, makes the control either the top or bottom window on the screen.

DYNAMIC void __fastcall SetZOrder(bool TopMost);

Description

Use SetZOrder to move rearrange overlapping controls within a parent control or overlapping windows on the screen. If the TopMost parameter is true, the control becomes the top control; otherwise, it becomes the bottom control.

Windowed controls always stack on top of non-windowed controls. Thus, if the Parent contains any non-windowed controls, calling SetZOrder with a TopMost value of false will still keep the windowed control above all the non-windowed controls.

After changing the order, SetZOrder invalidates the control to ensure repainting to reflect the new order.


TWinControl::ShowControl

TWinControl	See also

Ensures that a specified child control is visible.

virtual void __fastcall ShowControl(TControl* AControl);

Description

Call ShowControl to display a child control. Specify the control you want to ensure will be visible as the value of the AControl parameter.

The TWinControl method ShowControl simply calls the ShowControl method of the windowed control’s parent. Derived objects override ShowControl to perform whatever actions are necessary to allow the indicated child object to be visible. Possible actions include scrolling the particular child object into view, or changing to the appropriate notebook page.

ShowControl is a protected method used in the implementation of the Show method.


TWinControl::Update

TWinControl	See also 	Example

Processes any pending paint messages immediately.

virtual void __fastcall Update(void);

Description

Call Update to force the control to be repainted before any more, possibly time-consuming, processing takes place. Use Update to provide immediate feedback to the user that cannot wait for the Windows paint message to arrive. Update does not invalidate the control, but simply forces a repaint of any regions that have already been invalidated. Call Repaint instead if you need to invalidate the control as well.

Update calls the Windows API UpdateWindow function, which processes any pending paint messages. For more information, see the Win32 Developer's Reference (WIN32.HLP).


TWinControl::UpdateControlState

TWinControl	See also

Shows the windowed control, causing all parent objects to make any necessary adjustments.

void __fastcall UpdateControlState(void);

Description

UpdateControlState is used internally by C++Builder to show controls and create handles for controls at the time they are displayed. UpdateControlState calls the Show method to show the windowed control. To help ensure that the windowed control will be visible, it creates the window handle for the object or any parent objects that do not yet have one, and calls the ShowControl method of all parent controls to ensure that the control is in view.

UpdateControlState shows the control only if its parent is showing and the control’s Visible property is true.


TWinControl::WndProc

TWinControl 	See also

Provides specific message responses for the control.

struct TMessage

{

  Cardinal Msg;

  union

  {

    struct

    {

      Word WParamLo;

      Word WParamHi;

      Word LParamLo;

      Word LParamHi;

      Word ResultLo;

      Word ResultHi;

    };

    struct

    {

      int WParam;

      int LParam;

      int Result;

    };

  };

};

virtual void __fastcall WndProc(Messages::TMessage &Message);

Description

Override WndProc to change the initial Windows message handler for the control. The WindowProc property is initialized to point to the WndProc method.

WndProc for TWinControl overrides the parent class’s method to define responses for focus, mouse, and keyboard messages. It sends all others to its parent class’s WndProc.

When overriding WndProc to provide specialized responses to messages, call the parent class’s WndProc at the end to dispatch any unhandled messages.


Scope

Protected

Published

Accessibility

Read-only


Scope

Protected


Scope

Protected


Hierarchy

TObject

TPersistent

TComponent

TControl


TWordField

Hierarchy	Properties	Methods	Events	See also

TWordField represents an unsigned 16-bit integer field in a dataset.

Unit

db

Description

Word fields can hold values in the range 0 to 65535, and are used to hold values that are unsigned 16-bit whole numbers.

TWordField differs from its immediate ancestor TIntegerField only in the data type it represents. Except for the constructor and the DataSize property, all of the properties, methods, and events are the same as those of TIntegerField, and provide functionality that is useful for managing the value and properties of an integral numeric field in a database.


TWordField properties

TWordField	Alphabetically	Legend

In TWordField

DataSize

Derived from TIntegerField

AsFloat

AsInteger

AsString

AsVariant

MaxValue

MinValue

Value

Derived from TNumericField

DisplayFormat

EditFormat

Derived from TField

Alignment

AsBoolean

AsCurrency

AsDateTime

AttributeSet

Calculated

CanModify

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataType

DefaultExpression

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

NewValue

Offset

OldValue

Origin

ReadOnly

Required

Size

Text

ValidChars

Visible

Derived from TComponent

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

DesignInfo

Name

Owner

Tag

VCLComObject


TWordField properties

TWordField	By object	Legend

Alignment

AsBoolean

AsCurrency

AsDateTime

AsFloat

AsInteger

AsString

AsVariant

AttributeSet

Calculated

CanModify

ComObject

ComponentCount

ComponentIndex

Components

ComponentState

ComponentStyle

ConstraintErrorMessage

CurValue

CustomConstraint

DataSet

DataSize

DataType

DefaultExpression

DesignInfo

DisplayFormat

DisplayLabel

DisplayName

DisplayText

DisplayWidth

EditFormat

EditMask

EditMaskPtr

FieldKind

FieldName

FieldNo

ImportedConstraint

Index

IsIndexField

IsNull

KeyFields

Lookup

LookupCache

LookupDataSet

LookupKeyFields

LookupList

LookupResultField

MaxValue

MinValue

Name

NewValue

Offset

OldValue

Origin

Owner

ReadOnly

Required

Size

Tag

Text

ValidChars

Value

VCLComObject

Visible


TWordField::DataSize

TWordField	See also 	Example

Indicates the amount of memory needed to store the value of a word field in its native database format.

__property Word DataSize = {read=GetDataSize, nodefault};

Description

Check DataSize to determine the number of bytes required to store a word field component’s value. Use DataSize to determine the size needed for a buffer when working with the GetData and SetData methods.

For word fields, DataSize is always 2. This is the size of unsigned word values in the database tables, not the size of the LongInt data type used to store and manipulate values by TWordField.


TWordField events

TWordField	Alphabetically	Legend

Derived from TField

OnChange

OnGetText

OnSetText

OnValidate


TWordField events

TWordField	By object	Legend

OnChange

OnGetText

OnSetText

OnValidate


TWordField methods

TWordField	Alphabetically

In TWordField

~TWordField

Create

TWordField

Derived from TField

Assign

AssignValue

Clear

Destroy

FocusControl

GetData

IsBlob

IsValidChar

RefreshLookupList

SetData

SetFieldType

Validate

Derived from TComponent

DestroyComponents

Destroying

FindComponent

FreeNotification

FreeOnRelease

GetParentComponent

HasParent

InsertComponent

RemoveComponent

SafeCallException

Derived from TPersistent

GetNamePath

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance


TWordField methods

TWordField	By object

~TWordField

Assign

AssignValue

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

Clear

Create

DefaultHandler

Destroy

DestroyComponents

Destroying

Dispatch

FieldAddress

FindComponent

FocusControl

Free

FreeInstance

FreeNotification

FreeOnRelease

GetData

GetInterface

GetInterfaceEntry

GetInterfaceTable

GetNamePath

GetParentComponent

HasParent

InheritsFrom

InitInstance

InsertComponent

InstanceSize

IsBlob

IsValidChar

MethodAddress

MethodName

NewInstance

RefreshLookupList

RemoveComponent

SafeCallException

SetData

SetFieldType

TWordField

Validate


TWordField::TWordField

TWordField	See also

Creates an instance of TWordField.

__fastcall virtual TWordField(Classes::TComponent* AOwner);

Description

It is seldom necessary to call TWordField directly, because a word field component is instantiated automatically for all fields that contain only word values in a dataset. When calling the TWordField constructor, use the new keyword.

After calling the parent class’s constructor, TWordField sets

•	DataType to ftWord

•	MinValue to 0

•	MaxValue to 65535


TWordField::~TWordField

TWordField

~TWordField frees the memory associated with the TWordField object.

__fastcall virtual ~TWordField(void) { }

Description

Do not call ~TWordField directly. Instead, use the delete keyword on the object, which causes ~TWordField to be invoked automatically.


Scope

Published

Accessibility

Read-only


Scope

Published


Hierarchy

TObject

TPersistent

TComponent

TField

TNumericField

TIntegerField


TWriter

Hierarchy	Properties	Methods	See also

TWriter is a specialized filer object that writes data to its associated stream.

Unit

classes

Decription

TWriter is used internally by the VCL streaming system to write information associated with a component, such as published properties of components or custom property data, to a stream. TWriter handles the mechanics of writing the data associated with a component to a stream. It is the writer object, rather than the stream, that is responsible for handling the complexities of streaming components. These include methods for:

•	Writing different kinds of items to the associated stream.

•	Writing property deltas used for streaming inherited forms and properties with default values.

•	Writing nested groups of items or collections to the stream.

Other methods and properties of TWriter are used for interacting with stream and component objects.

Do not directly create writer objects. Writers are automatically created in stream object methods or in global routines that initiate the streaming process. These include:

•	the global routine ObjectTextToBinary procedure, which directly creates a writer.

•	the global WriteComponentResFile function, which creates a file stream that creates a writer.

•	the TStream::WriteDescendent method, which creates a writer object.

Once the streaming process is underway, programs do not need to directly manipulate writer objects. The interaction between the writer, component, and stream objects happens automatically in methods of these objects that make calls to each other.


TWriter properties

TWriter	Alphabetically

In TWriter

Position

RootAncestor

Derived from TFiler

Ancestor

IgnoreChildren

Root


TWriter properties

TWriter	By object

Ancestor

IgnoreChildren

Position

Root

RootAncestor


TWriter::Position

TWriter	See also

Represents the current writing position in the associated stream.

__property int Position = {read=GetPosition, write=SetPosition, nodefault};

Desription

Position is used internally by writer objects to indicate the current writing position in the stream.

The value of Position will be inside the most recent buffer block read or the next block to be written. Thus, for writing, Position will generally be less than the stream's Position. When Position is set to a location outside the current buffer, the writer’s buffer is flushed to the stream.


TWriter::RootAncestor

TWriter	See also

Represents the ancestor of the component in the Root property.

__property TComponent* RootAncestor = {read=FRootAncestor, write=FRootAncestor};

Description

RootAncestor is used internally by writer objects for dealing with form inheritance. It is used to iterate through ancestor components when writing properties in inherited forms.

RootAncestor is always the ancestor form. For each component in Root, which is the inherited form, the Ancestor property tracks a corresponding component in RootAncestor.

The writer object iterates through each of the Root form's owned components, comparing each to the corresponding component in the RootAncestor form. It then writes only those properties in the current component that differ in some way from those in the Ancestor component.


TWriter methods

TWriter	Alphabetically

In TWriter

~TWriter

DefineBinaryProperty

DefineProperty

FlushBuffer

TWriter

Write

WriteBoolean

WriteChar

WriteCollection

WriteComponent

WriteDescendent

WriteFloat

WriteIdent

WriteInteger

WriteListBegin

WriteListEnd

WriteRootComponent

WriteSignature

WriteStr

WriteString

Derived from TFiler

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWriter methods

TWriter	By object

~TWriter

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

DefineBinaryProperty

DefineProperty

Dispatch

FieldAddress

FlushBuffer

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException

TWriter

Write

WriteBoolean

WriteChar

WriteCollection

WriteComponent

WriteDescendent

WriteFloat

WriteIdent

WriteInteger

WriteListBegin

WriteListEnd

WriteRootComponent

WriteSignature

WriteStr

WriteString


TWriter::DefineBinaryProperty

TWriter	See also

Treats unformatted data as if it were the value of a published property, and writes it directly to a memory stream.

typedef void __fastcall (__closure *TStreamProc)(TStream* Stream);

virtual void __fastcall DefineBinaryProperty(const System::AnsiString Name, TStreamProc &ReadData, TStreamProc &WriteData, bool HasData);

Description

DefineBinaryProperty is called internally by the DefineProperties method of an object that has data it needs to store. DefineProperties takes a generic filer object as its parameter.

For writing binary data DefineProperties takes a TWriter object and then calls its DefineBinaryProperty method. DefineBinaryProperty writes the property’s name and it’s data, but only if the HasData parameter is true. Otherwise it does nothing.

The Name parameter specifies the name of the “fake” property to be written to the stream. A “fake” property is a property that is not published, and that exists only in the code for the DefineBinaryProperty method. The Top and Left properties of a non-visual component are examples of “fake” properties. These are also called “defined properties” or “custom defined properties.”

The TStreamProc type is the type of the ReadData and WriteData parameters. It is the method-pointer type that points to a procedure (defined in the storing object) that reads or writes a binary representation of the object's data directly to or from the stream passed as its Stream parameter. For TWriter the ReadData parameter is ignored.

The HasData parameter determines at run time whether the "fake" property has data to store (write).

Defined binary properties are quite rare. VCL objects that store graphics as binary data are the most common use of filer objects to store and retrieve that data. More commonly, objects use the DefineProperty method. The difference between DefineBinaryProperty and DefineProperty is that with DefineBinaryProperty the component reads or writes the binary property directly to or from a memory stream, rather than going through a filer object.

Note:	Streamable objects that are descended from TPersistent inherit a DefineProperties method, however DefineProperties does not do anything until TComponent. It is TComponent’s DefineProperties method that calls the writer’s DefineBinaryProperty when writing out binary data.


TWriter::DefineProperty

TWriter	See also

Defines data the writer object writes as if the data were a property.

typedef void __fastcall (__closure *TReaderProc)(TReader* Reader);

typedef void __fastcall (__closure *TWriterProc)(TWriter* Writer);

virtual void __fastcall DefineProperty(const System::AnsiString Name, TReaderProc &ReadData, TWriterProc &WriteData, bool HasData);

Description

DefineProperty is called internally by the DefineProperties method of an object that has data it needs to store. DefineProperties takes a generic filer object as its parameter. For writing data, DefineProperties takes a TWriter object and calls its DefineProperty method. DefineProperty then writes the property’s name and it’s data, but only if the HasData parameter is true. Otherwise it does nothing.

The Name parameter specifies the name of the “fake” property to be written to the stream.

The TWriterProc type is the type of the WriteData parameter. It is the method-pointer type that points to a procedure (defined in the component object) that writes the object's data, that represents a property value, to the writer object. For TWriter the ReadData parameter is ignored.

The HasData parameter determines at run time whether the "fake" property has data to store (write). Thus, HasData is used only by writer objects when writing data.

The difference between DefineBinaryProperty and DefineProperty is that with DefineBinaryProperty, the binary data is written directly to a stream object, rather than going through a filer object.

When writing a component that has special (large) data storage requirements, the component’s DefineProperties can be overriden. For each special or “fake” property item, call the TFiler::DefineProperty method or TFiler::DefineBinaryProperty. For the ReadData and WriteData parameters, pass in methods of the component that know how to handle that special data type. When reading, ReadData is called. When writing, WriteData is called.

Note:	When defining properties, a component should be aware of the Ancestor property, which, if non-NULL, indicates that the component should only write the values of properties that differ from those inherited from Ancestor.


TWriter::~TWriter

TWriter	See also

Destroys of an instance of a writer.

__fastcall virtual ~TWriter(void);

Description

Do not call ~TWriter. Writers are created indirectly by the global routines or stream methods that use them. When these routines are finished, they handle disposing of the writer.

~TWriter writes the buffer before calling the parent class’s destructor which frees the buffer.


TWriter::FlushBuffer

TWriter

Synchronizes the writer's buffer with the associated stream by writing the current buffer.

virtual void __fastcall FlushBuffer(void);

Description

FlushBuffer is not generally used except for internal implementation in C++Builder.

FlushBuffer writes the current buffer to the stream, then resets an internal pointer to the correct position.


TWriter::Write

TWriter	See also

Writes Count bytes from Buf to the writer object's associated stream.

void __fastcall Write(const void *Buf, int Count);

Descripiton

Do not call Write directly. It is used internally to write data to the stream. Many other writer methods call Write, usually after setting pertinent values or verifying data types.


TWriter::WriteBoolean

TWriter	See also

Writes the Boolean value passed in Value to the writer object's stream.

void __fastcall WriteBoolean(bool Value);

Description

WriteBoolean is used internally by the VCL streaming system to write component properties to a stream. Use WriteBoolean for writing component boolean properties to streams.

WriteBoolean checks to ensure that Value is the correct type before calling Write to write the boolean value and its value type to the stream.


TWriter::WriteChar

TWriter	See also

Writes the character passed in Value to the writer object's stream.

void __fastcall WriteChar(char Value);

Description

WriteChar is used internally by the VCL streaming system to write component properties to a stream. Use WriteChar for writing component character properties to streams.

WriteChar calls WriteString which checks to ensure that Value is the correct type before calling Write to write the character and its value type to the stream.

Note:	WriteChar calls StringChar to enable writing character properties that are upwardly compatable with string properties.


TWriter::WriteCollection

TWriter	See also

Writes the collection of objects passed in Value to the writer object's stream.

void __fastcall WriteCollection(TCollection* Value);

Description

WriteCollection is used internally by the VCL streaming system to write component properties to a stream. Use WriteCollection for writing component properties that are collections to streams.

WriteCollection checks to ensure that Value is the correct type before calling Write to write the collection and its value type to the stream. WriteCollection bounds the collection with start-of-list and end-of- list markers.


TWriter::WriteComponent

TWriter	See also

Writes the component specified by Component to a stream.

void __fastcall WriteComponent(TComponent* Component);

Description

Never call WriteComponent directly. WriteComponent is recursively called for each owned component in Root.

WriteComponent sets the csWriting state in Component's ComponentState property before calling the WriteState method of Component and clears the csWriting flag when WriteState returns.

Note:	The sequence of events is as follows: the writer’s WriteComponent method calls the Component’s WriteState method, which calls the writer’s WriteData method. That method writes the properties for each child component, then calls WriteComponent.

Because the Component’s WriteState is virtual, it is the Component’s only opportunity to prepare itself to be streamed (i.e. to consolidate its data.)


TWriter::WriteDescendent

TWriter	See also

Triggers the writing of descendent components in inherited forms.

void __fastcall WriteDescendent(TComponent* Root, TComponent* AAncestor);

Description

Never call WriteDescendent directly. It is part of a sequence of calls used for streaming descendent components in inherited forms.

WriteDescendent sets the writer object's Ancestor and RootAncestor properties to the value passed in AAncestor, sets the Root property to the value passed in Root, then calls WriteSignature and WriteComponent to write Root and any components it owns to the writer object's stream.

WriteDescendent differs from WriteComponent in that, by setting Ancestor, it uses Ancestor's property values as the defaults, rather than those defined by Root's type.


TWriter::WriteFloat

TWriter	See also

Writes the floating-point value passed in Value to the writer object's stream.

void __fastcall WriteFloat(Extended Value);

Description

WriteFloat is used internally by the VCL streaming system to write component properties to a stream. Use WriteFloat for writing floating point data to streams.

WriteFloat checks to ensure that Value is the correct type before calling Write to write the float value and its value type to the stream.


TWriter::WriteIdent

TWriter	See also

Writes the identifier passed in Ident to the writer object's stream.

void __fastcall WriteIdent(const System::AnsiString Ident);

Description

WriteIdent is used internally by the VCL streaming system to write component properties to a stream. Use WriteIdent for writing component identifier properties to streams. Component names and enumerated type elements are examples of strings which must be restricted to Pascal identifier syntax.

WriteFloat checks to ensure that Value is the correct type before calling Write to write the identifier and its value type to the stream.


TWriter::WriteInteger

TWriter	See also

Writes the integer value passed in Value to the writer object's stream.

void __fastcall WriteInteger(int Value);

Description

WriteInteger is used internally by the VCL streaming system to write component properties to a stream. Use WriteInteger for writing component integer properties to streams.

WriteInteger checks to ensure that Value is the correct type before calling Write to write the integer value and its value type to the stream. WriteInteger handles integers of different sizes.


TWriter::WriteListBegin

TWriter	See also

Writes a start-of-list marker to the writer object's associated stream.

void __fastcall WriteListBegin(void);

Description

WriteListBegin is used by other methods that iterate through a group of items about to be written to the stream. WriteListBegin writes a start-of-list marker to the writer object's associated stream. Every call to WriteListBegin must have a corresponding call to WriteListEnd.


TWriter::WriteListEnd

TWriter	See also

Writes an end-of-list marker to the writer object's associated stream.

void __fastcall WriteListEnd(void);

Description

WriteListEnd is used by other methods that iterate through a group of items that are sequentially written to the stream during a single process.

A call to WriteListEnd is generally preceded by a writing loop. A call to WriteListEnd must correspond to a preceding call to WriteListBegin.


TWriter::WriteRootComponent

TWriter	See also

Calls the WriteDescendent method.

void __fastcall WriteRootComponent(TComponent* Root);

Description

WriteRootComponent is provided for backward compatibility only.


TWriter::WriteSignature

TWriter

Writes a filer signature to the writer object's associated stream.

void __fastcall WriteSignature(void);

Description

WriteSignature is used internally by several methods that write the filer signature before processing some action. For example, the WriteRootComponent method calls WriteSignature before writing its component to the stream. By checking for the signature before loading objects, reader objects can guard against inadvertently reading invalid or corrupted data.

The filer signature is a four-character sequence. For this version of C++Builder, the signature is 'TPF0'.


TWriter::WriteStr

TWriter	See also

Writes raw data to the writer object's stream.

void __fastcall WriteStr(const System::AnsiString Value);

Description

Do not call WriteStr directly. WriteStr is for internal use by certain VCL components. WriteStr writes the string passed in Value to the writer object's stream.

Warning:	Always use WriteString for writing component strings to streams. WriteStr can corrupt data if not used correctly.


TWriter::WriteString

TWriter	See also

Writes tagged data to the writer object's stream.

void __fastcall WriteString(const System::AnsiString Value);

Description

WriteString is used internally by the VCL streaming system to write component properties to a stream. WriteString is otherwise only used by component writers in the DefineProperties and WriteData procedures.

WriteString writes the string passed in Value to the writer object's stream. WriteString checks to ensure that Value is the correct type before calling Write to write the string and its value type to the stream.

Warning:	Always use WriteString for writing component strings to streams. The similarly-named WriteStr method is for internal use by certain VCL components and can corrupt data if not used correctly.


TWriter::TWriter

TWriter 	See also

Creates a new TWriter object.

__fastcall virtual ~TWriter(void);

Description

Do not directly create writer objects. Writers are automatically created in stream object methods or in global routines that initiate the streaming process. These include:

•	the global routine ObjectTextToBinary procedure, which directly creates a writer.

•	the global WriteComponentResFile function, which creates a file stream that creates a writer.

•	the TStream::WriteDescendent method, which creates a writer object.


Hierarchy

TObject

TFiler


TWinSocketStream

Hierarchy	Properties	Methods	See also

TWinSocketStream is a stream that provides services which allow applications to read from or write to socket connections.

Unit

scktcomp

Description

Use TWinSocketStream to read or write information over a blocking socket connection. Windows socket objects include methods to read from or write to the socket connection they represent. However, these methods do not provide a mechanism for timing out when the socket connection is dropped or for waiting until the socket connection is ready before reading.

When the socket is a non-blocking socket, this lack of a timeout or waiting mechanism is not a problem, because reading and writing occur asynchronously in response to notifications from the socket connection. For blocking sockets, however, these mechanisms provided by TWinSocketStream are necessary so that the application using the socket does not hang indefinitely.

To use a Windows socket stream, create an instance of TWinSocketStream, use the methods of the stream to read or write the data, and then free the Windows socket stream.

Note:	TWinSocketStream does not work with non-blocking sockets.


TWinSocketStream properties

TWinSocketStream	Alphabetically

In TWinSocketStream

TimeOut

Derived from TStream

Position

Size


TWinSocketStream properties

TWinSocketStream	By object

Position

Size

TimeOut


TWinSocketStream::TimeOut

TWinSocketStream	See also

Specifies the time, in milliseconds, that the socket stream should wait before timing out on a read or write call.

__property int TimeOut = {read=FTimeout, write=FTimeout, nodefault};

Description

Set TimeOut to the amount of time that should elapse before a read or write operation aborts under the assumption that the socket connection has failed.


TWinSocketStream methods

TWinSocketStream	Alphabetically

In TWinSocketStream

~TWinSocketStream

Read

Seek

TWinSocketStream

WaitForData

Write

Derived from TStream

CopyFrom

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes

Derived from TObject

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

SafeCallException


TWinSocketStream methods

TWinSocketStream	By object

~TWinSocketStream

ClassInfo

ClassName

ClassNameIs

ClassParent

ClassType

CleanupInstance

CopyFrom

DefaultHandler

Dispatch

FieldAddress

Free

FreeInstance

GetInterface

GetInterfaceEntry

GetInterfaceTable

InheritsFrom

InitInstance

InstanceSize

MethodAddress

MethodName

NewInstance

Read

ReadBuffer

ReadComponent

ReadComponentRes

ReadResHeader

SafeCallException

Seek

TWinSocketStream

WaitForData

Write

WriteBuffer

WriteComponent

WriteComponentRes

WriteDescendent

WriteDescendentRes


TWinSocketStream::TWinSocketStream

TWinSocketStream	See also 	Example

Creates an instance of TWinSocketStream for a Windows socket object.

__fastcall TWinSocketStream(TCustomWinSocket* ASocket, int TimeOut);

Description

Call TWinSocketStream indirectly, using the new keyword, to obtain an instance of TWinSocketStream for reading from or writing to the socket connection represented by the ASocket parameter. ASocket should be the endpoint of an open blocking socket connection to another Windows socket.

TWinSocketStream associates the stream with the socket connection, and allocates helper objects to allow it to determine when the socket connection is ready for reading or writing. The TimeOut property is initialized to the value of the TimeOut parameter.

If ASocket represents a non-blocking socket connection, TWinSocketStream throws an ESocketError exception.


TWinSocketStream::~TWinSocketStream

TWinSocketStream	See also

Destroys an instance of TWinSocketStream.

__fastcall virtual ~TWinSocketStream(void);

Description

Do not call ~TWinSocketStream directly in an application. Instead use the delete keyword.

Free the TWinSocketStream object when it is no longer needed for reading from or writing to the socket connection.

~TWinSocketStream frees the helper objects allocated in the TWinSocketStream method before calling the default destructor.


TWinSocketStream::Read

TWinSocketStream	See also

Reads up to Count bytes from the socket connection into Buffer.

virtual int __fastcall Read(void *Buffer, int Count);

Description

Use Read to read data from the socket connection when the number of bytes to be transferred is unknown. Buffer must have at least Count bytes allocated to hold the data that is read from the connection. Read returns the number of bytes actually transferred (which may be less than the number requested in Count.)

Read may return 0 if the socket connection is extremely slow and the read operation has not completed after TimeOut milliseconds. This ensures that the Read method does not hang indefinitely when a problem occurs with the socket connection.

To guard against the Read method timing out because of a slow connection, set Count fairly low, and make several calls to Read, rather than fewer calls with a large value of Count.

To ensure that the socket connection is ready to send data before calling Read, use the WaitForData method.

Unlike the ReadBuffer method, Read does not throw an exception if Count bytes are not read from the socket connection.


TWinSocketStream::Seek

TWinSocketStream	See also

Always returns 0.

virtual int __fastcall Seek(int Offset, Word Origin);

Description

Seek overrides the parent class’s method to always set the Position property of the TWinSocketStream object to 0. Socket connections do not support random access. The Position property of a Windows socket stream can only reflect the position at the beginning of all remaining data.


TWinSocketStream::WaitForData

TWinSocketStream	See also

Waits up to Timeout milliseconds for the socket connection to be ready to transfer data.

bool __fastcall WaitForData(int Timeout);

Description

Call WaitForData to ensure that the socket connection is ready to read or write information. WaitForData returns true if the socket connection is ready. WaitForData returns false if the socket connection is not ready after Timeout milliseconds elapse.

Call WaitForData before reading or writing information over the socket connection. Otherwise, Read or Write method calls may time out before any data is transferred.


TWinSocketStream::Write

TWinSocketStream	See also 	Example

Writes Count bytes from Buffer to the socket connection.

virtual int __fastcall Write(const void *Buffer, int Count);

Description

Use Write to write data from a Buffer to the socket connection. Write returns the number of bytes transferred.

Write may return 0 if the socket connection is extremely slow and the write operation has not completed after TimeOut milliseconds. This ensures that the Write method does not hang indefinitely when a problem occurs with the socket connection.

To guard against the Write method timing out because of a slow connection, set Count fairly low, and make several calls to Write, rather than fewer calls with a large value of Count.

Unlike the WriteBuffer method, Write does not throw an exception if Count bytes are not written. For example, if the connection is too slow to transfer all the data, Write will return 0, where WriteBuffer will throw an exception.


Hierarchy

TObject

TStream


Application variable

Units

Forms and HTTPApp

There are two versions of the Application variable, one for standard applications (declared in the Forms header), the other for Web server applications (Declared in the HTTPApp header). The Web server Application variable is initialized as either an ISAPI application (in ISAPIApp) or a CGI application (in CGIApp). A single project should include only one of these. Do not #include more than one of these headers (Forms, CGIApp, and ISAPIApp) in a project. When a program starts running, C++Builder instantiates the Application variable as declared in the header that is #included in the project, and calls its Initialize method, its CreateForm method, and then its Run method. The behavior of the application depends on the implementation of these methods in the class of Application object that gets created.

Application variable for standard applications

Application variable for Web server applications


Application variable (for standard applications)

See also 	Example

The Application variable in the Forms header is used to declare an instance of an application for a project.

Unit

Forms

extern PACKAGE TApplication* Application;

Description

By default, when a new project is created, C++Builder constructs an application object and assigns it to Application. Application has several properties which can be  used to get information about an application while it runs. Refer to TApplication component for the list of properties.


Application variable (for Web server applications)

See also

The Application variable in the HTTPApp header is used to declare an instance of a web server application for an internet project.

Unit

HTTPApp

extern PACKAGE TWebApplication* Application;

Description

By default, when a new internet server project is created, C++Builder constructs an application object and assigns it to Application. If the project represents a CGI or Win-CGI server application, Application is initialized to a TCGIApplication object. If the project represents an ISAPI or NSAPI server application, Application is initialized to a TISAPIApplication object. Which type of TWebApplication object gets created depends on whether the project #includes the ISAPIApp header or the CGIApp header.


Automation variable

Automation is for backward compatibility with C++Builder 1.0.

Unit

OleAuto

extern PACKAGE TAutomation* Automation;

Description

Declarations in the OleAuto header are provided for backward compatibility.

Note:	New implementations of OLE and ActiveX in the current version of C++Builder have replaced declarations in the OleAuto header. A description of the Automation variable follows:

Automation is a global instance of the automation manager class. It serves as the Automation manager for an OLE automation server written with C++Builder.

When creating an OLE automation object (an object derived from the TAutoObject class in the OleAuto header) the file that defines that object must call Automation.RegisterClass, passing a record of type TAutoClassInfo. The Automation manager then handles all interactions between your automation object and the OLE automation API.


CmdLine variable

See also

CmdLine is a pointer to the command-line arguments specified when the application is invoked.

Unit

System

extern PACKAGE char *CmdLine;

Description

In a program, the CmdLine variable contains a pointer to a null-terminated string that contains the command-line arguments specified when the application was started. Use ParamStr to access individual arguments.

In a library (DLL), CmdLine is NULL.


CmdShow variable

CmdShow is passed to the Windows ShowWindow WinAPI routine.

Unit

System

extern PACKAGE int CmdShow;

Description

In a program, the CmdShow variable contains the parameter value that Windows expects to be passed to ShowWindow when the application creates its main window.

In a library (DLL), CmdShow is always zero.


Currency and date/time formatting variables

See also 	Example

Unit

SysUtils

The following are a set of variables used to define the format for date and time strings:

extern PACKAGE System::AnsiString CurrencyString;

extern PACKAGE Byte CurrencyFormat;

extern PACKAGE Byte NegCurrFormat;

extern PACKAGE char ThousandSeparator;

extern PACKAGE char DecimalSeparator;

extern PACKAGE Byte CurrencyDecimals;

extern PACKAGE char DateSeparator;

extern PACKAGE System::AnsiString ShortDateFormat;

extern PACKAGE System::AnsiString LongDateFormat;

extern PACKAGE char TimeSeparator;

extern PACKAGE System::AnsiString TimeAMString;

extern PACKAGE System::AnsiString TimePMString;

extern PACKAGE System::AnsiString ShortTimeFormat;

extern PACKAGE System::AnsiString LongTimeFormat;

extern PACKAGE System::AnsiString ShortMonthNames[12];

extern PACKAGE System::AnsiString LongMonthNames[12];

extern PACKAGE System::AnsiString ShortDayNames[7];

extern PACKAGE System::AnsiString LongDayNames[7];

Description

The SysUtils header includes a number of variables that are used by the date and time routines. Values are assigned to these variables to define the formats of date and time strings. The initial values of these variables are fetched from the system registry using the GetLocaleInfo function in the Win32 API. VCL (non-console) applications will automatically update these formatting variables in response to WM_WININICHANGE messages. Application.UpdateFormatSettings will either allow or not allow changes in system settings. The default is true. Set this property to false to prevent the system settings from changing.

The description of each variable specifies the LOCALE_XXXX constant used to fetch the initial value using the GetLocaleInfo Win32 API.

Typed constant	Defines
CurrencyString	CurrencyString defines the currency symbol (or characters) used in floating-point to decimal conversions. The initial value is fetched from LOCALE_SCURRENCY.
CurrencyFormat	CurrencyFormat defines the currency symbol placement and separation used in floating-point to decimal conversions. Possible values are:0 = '$1'1 = '1$'2 = '$ 1'3 = '1 $'The initial value is fetched from LOCALE_ICURRENCY.
NegCurrFormat	NegCurrFormat defines the currency format used in floating-point to decimal conversions of negative numbers. Possible values are: 0 = ($1)    4 = (1$)    8 = -1 $    12 = $ -11 = -$1     5 = -1$     9 = -$ 1    13 = 1- $2 = $-1     6 = 1-$    10 = 1 $-    14 = ($ 1)3 = $1-     7 = 1$-    11 = $ 1-    15 = (1 $) The initial value is fetched from LOCALE_INEGCURR.
ThousandSeparator	ThousandSeparator is the character used to separate thousands in numbers with more than three digits to the left of the decimal separator. The initial value is fetched from LOCALE_STHOUSAND.
DecimalSeparator	DecimalSeparator is the character used to separate the integer part from the fractional part of a number. The initial value is fetched from LOCALE_SDECIMAL.
CurrencyDecimals	CurrencyDecimals is the number of digits to the right of the decimal point in a currency amount. The initial value is fetched from LOCALE_ICURRDIGITS.
DateSeparator	DateSeparator is the character used to separate the year, month, and day parts of a date value. The initial value is fetched from LOCATE_SDATE.
ShortDateFormat	ShortDateFormat is the format string used to convert a date value to a short string suitable for editing. For a complete description of date and time format strings, refer to the documentation for the FormatDateTime function. The short date format should only use the date separator character and the  m, mm, d, dd, yy, and yyyy format specifiers. The initial value is fetched from LOCALE_SSHORTDATE..
LongDateFormat	LongDateFormat is the format string used to convert a date value to a AnsiString suitable for display but not for editing. For a complete description of date and time format strings, refer to the documentation for the FormatDateTime function. The initial value is fetched from LOCALE_SLONGDATE.
TimeSeparator	TimeSeparator is the character used to separate the hour, minute, and second parts of a time value. The initial value is fetched from LOCALE_STIME.
TimeAMString	TimeAMString is the suffix string used for time values between 00:00 and 11:59 in 12-hour clock format. The initial value is fetched from LOCALE_S1159.
TimePMString	TimePMString is the suffix string used for time values between 12:00 and 23:59 in 12-hour clock format. The initial value is fetched from LOCALE_S2359.
ShortTimeFormat	ShortTimeFormat is the format string used to convert a time value to a short string with only hours and minutes. The default value is computed from LOCALE_ITIME and LOCALE_ITLZERO.
LongTimeFormat	LongTimeFormat is the format string used to convert a time value to a AnsiString with hours, minutes, and seconds. The default value is computed from LOCALE_ITIME and LOCALE_ITLZERO.
ShortMonthNames	ShortMonthNames is the array of strings containing short month names. The mmm format specifier in a format string passed to FormatDateTime causes a short month name to be substituted. The default values are fecthed from the LOCALE_SABBREVMONTHNAME system locale entries.
LongMonthNames	LongMonthNames is the array of strings containing long month names. The mmmm format specifier in a format string passed to FormatDateTime causes a long month name to be substituted. The default values are fecthed from the LOCALE_SMONTHNAME system locale entries.
ShortDayNames	ShortDayNames is the array of strings containing short day names. The ddd format specifier in a format string passed to FormatDateTime causes a short day name to be substituted. The default values are fecthed from the LOCALE_SABBREVDAYNAME system locale entries.
LongDayNames	LongDayNames is the array of strings containing long day names. The dddd format specifier in a format string passed to FormatDateTime causes a long day name to be substituted. The default values are fecthed from the LOCALE_SDAYNAME system locale entries.


CurrentGroup variable

See also

CurrentGroup is used by some internal systems to keep track of which objects are associated with which packages.

Unit

classes

extern PACKAGE int CurrentGroup;

Description

When a design-time package registers a property editor class, the registration list has to keep track of what package that property editor class is associated with, so that if that package needs to be unloaded at design time (to recompile the package), the registration list will know which property classes to delete from its list. CurrentGroup is that indicator; It gets incremented every time a package is loaded at design time.

CurrentGroup is used to write design-time tools that keep track of things stored in other packages.


DateDelta constant

See also

DateDelta is the correction factor when computing the difference between two date and time types that do not begin in the same year.

Unit

SysUtils

#define DateDelta (int)(693594)

Description

DateDelta is number of days between 1/1/0001 and 12/31/1899. It is used to allow arithmetic comparisons of date and time types that do not begin in the same year. For example, TDateTime begins with 12/31/1899, whereas TTimeStamp begins with 1/1/0001. The correction is for the number of days that have already passed. So, for TDateTime 12/31/1899 is represented as zero.


DBIResult type

See also

DBIResult is used to specify a BDE error code .

Unit

BDE

typedef Word DBIResult;

Description

DBIResult is used to specify a Borland Database Engine error code for the DBIError procedure. Use DBIResult to declare the return value when making direct API calls to the BDE.


DDBsOnly variable

See also

DDBsOnly determines whether bitmap handles are created as device-dependent bitmaps (DDB).

Unit

Graphics

extern PACKAGE bool DDBsOnly;

Description

Set DDBsOnly to force all bitmap handles to be created as device-dependent bitmaps (DDB). The VCL default bitmap handle format is DIB (device-independent bitmap).

Setting DDBsOnly to true undercuts much of the VCL graphics architecture; it should not be used unless it is absolutely required. Examples of when to set it to true are:

•	You have a graphics-intensive application that does bitmap operations that Windows does not support with DIBs; you can either set each bitmap object to DDB before you access its handle property, or you can set this global variable to true.

•	Your application uses hundreds of very small bitmaps. Each DIB consumes a separate 4k memory page. DIBs are less efficient for storing many small images than DDBs.  Before resorting to changing the DDBsOnly flag to address this, consider switching your code to use image lists instead of individual tiny bitmaps.  Image lists are more efficient than DIBs and DDBs for storing many same-size small images.

Note:	Setting DDBsOnly to true introduces the issue of image alteration.  When a BMP file or resource is loaded into a DDB, the color information in the original image is changed to fit the pixel format of the current video device and mode.  If you read an image, touch its handle, and write it out, you will not get the same file you read in.  DIBs solve this problem. Do not change DDBsOnly unless you have a specific need for device-dependent bitmaps and are willing to accept the image-altering DDB side effects.


Default8087CW variable

See also

Default8087CW is the Default 8087 control word.

Unit

System

extern PACKAGE Word Default8087CW;

Description

Default8087CW is the value to which the Floating Point Unit (FPU) control register is set. The FPU control word includes bits that control the FPU's precision, rounding mode, and whether exceptions generate signals if they occur. See Intel's processor documentation for details.

The Set8087CW routine allows the programmer to have direct access to the Default8087CW. Setting the floating-point precision and rounding mechanism can be useful if you are reusing old code that is sensitive to the floating-point precision standard used. However, be aware that using this routine to change the value of the 8087CW will change the behavior of the program’s FP calculations. It is the programmer’s responsibility to reset it.


DLLProc variable

DLLProc is a pointer to a function invoked by a DLL entry point.

Unit

SysInit

extern PACKAGE void *DllProc;

Description

DLLProc is used to specify a function that is invoked every time a DLL's entry point is called. A function assigned to DLLProc must take one parameter of type int.

When the function is invoked, this parameter contains a value between 0 and 3 as defined by the following group of constants in the Windows header file:

const

  DLL_PROCESS_DETACH = 0;

  DLL_PROCESS_ATTACH = 1;

  DLL_THREAD_ATTACH  = 2;

  DLL_THREAD_DETACH  = 3;

For further details on the meaning of these constants, please refer to the description of the DllEntryPoint function in the Win32 API.


ErrorAddr variable

See also

ErrorAddr contains the address of a statement causing a runtime error.

Unit

System

extern PACKAGE void *ErrorAddr;

Description

If a program terminates normally or stops due to a call to Halt, ErrorAddr is NULL. If a program ends because of a run-time error, ErrorAddr contains the address of the statement in error.


FindGlobalComponent variable

See also

FindGlobalComponent returns a top-level container component.

Unit

Classes

typedef TComponent* __fastcall (*TFindGlobalComponent)(const System::AnsiString Name);

extern PACKAGE TFindGlobalComponent FindGlobalComponent;

Description

FindGlobalComponent is a function pointer used by the streaming system to implement form linking. When a component property refers to a component on another form, data module, or other top-level container component, the streaming system calls FindGlobalComponent to locate the root object in the form linking reference (e.g. Form1 in "Form1->Edit1").  If the object cannot be found, FindGlobalComponent returns NULL.


Format strings

Format strings specify required formats to formatting routines.

Description

Format strings passed to the string formatting routines contain two types of objects--plain characters and format specifiers. Plain characters are copied verbatim to the resulting string. Format specifiers fetch arguments from the argument list and apply formatting to them.

Format specifiers have the following form:

"%" [index ":"] ["-"] [width] ["." prec] type

A format specifier begins with a % character. After the % come the following, in this order:

An optional argument index specifier, [index ":"]

An optional left justification indicator, ["-"]

An optional width specifier, [width]

An optional precision specifier, ["." prec]

The conversion type character, type

The following table summarizes the possible values for type:

d	Decimal. The argument must be an integer value. The value is converted to a string of decimal digits. If the format string contains a precision specifier, it indicates that the resulting string must contain at least the specified number of digits; if the value has less digits, the resulting string is left-padded with zeros.
e	Scientific. The argument must be a floating-point value. The value is converted to a string of the form "-d.ddd...E+ddd". The resulting string starts with a minus sign if the number is negative. One digit always precedes the decimal point.
	The total number of digits in the resulting string (including the one before the decimal point) is given by the precision specifier in the format string--a default precision of 15 is assumed if no precision specifier is present. The "E" exponent character in the resulting string is always followed by a plus or minus sign and at least three digits.
f	Fixed. The argument must be a floating-point value. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative.
	The number of digits after the decimal point is given by the precision specifier in the format string--a default of 2 decimal digits is assumed if no precision specifier is present.
g	General. The argument must be a floating-point value. The value is converted to the shortest possible decimal string using fixed or scientific format. The number of significant digits in the resulting string is given by the precision specifier in the format string--a default precision of 15 is assumed if no precision specifier is present.
	Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format.
n	Number. The argument must be a floating-point value. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The "n" format corresponds to the "f" format, except that the resulting string contains thousand separators.
m	Money. The argument must be a floating-point value. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, DecimalSeparator, and CurrencyDecimals global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panel. If the format string contains a precision specifier, it overrides the value given by the CurrencyDecimals global variable.
p	Pointer. The argument must be a pointer value. The value is converted to a string of the form "XXXX:YYYY" where XXXX and YYYY are the segment and offset parts of the pointer expressed as four hexadecimal digits.
s	String. The argument must be a character, a string, or a PChar value. The string or character is inserted in place of the format specifier. The precision specifier, if present in the format string, specifies the maximum length of the resulting string. If the argument is a string that is longer than this maximum, the string is truncated.
x	Hexadecimal. The argument must be an integer value. The value is converted to a string of hexadecimal digits. If the format string contains a precision specifier, it indicates that the resulting string must contain at least the specified number of digits; if the value has fewer digits, the resulting string is left-padded with zeros.
Conversion characters may be specified in uppercase as well as in lowercase--both produce the same results.

For all floating-point formats, the actual characters used as decimal and thousand separators are obtained from the DecimalSeparator and ThousandSeparator global variables.

Index, width, and precision specifiers can be specified directly using decimal digit string (for example "%10d"), or indirectly using an asterisk character (for example "%*.*f"). When using an asterisk, the next argument in the argument list (which must be an integer value) becomes the value that is actually used. For example,

TVarRec args[3] = {8,2,123.456};

Format("%*.*f", args, 2);

is the same as

Format("%8.2f", 123.456, 0);

A width specifier sets the minimum field width for a conversion. If the resulting string is shorter than the minimum field width, it is padded with blanks to increase the field width. The default is to right-justify the result by adding blanks in front of the value, but if the format specifier contains a left-justification indicator (a "-" character preceding the width specifier), the result is left-justified by adding blanks after the value.

An index specifier sets the current argument list index to the specified value. The index of the first argument in the argument list is 0. Using index specifiers, it is possible to format the same argument multiple times. For example "Format('%d %d %0:d %1:d', [10, 20])" produces the string '10 20 10 20'.

The format strings are used by the following routines:

•	Format function

•	FormatBuf  function

•	FmtStr  routine

•	StrFmt  function

•	StrLFmt  function


HInstance variable

HInstance is the handle provided by Windows for an application or library.

Unit

SysInit

extern PACKAGE int HInstance;

Description

HInstance contains the instance handle of the application or library as provided by the Windows environment.


IsConsole variable

See also

IsConsole is a bool varible which is true if the module was compiled as a console application.

Unit

System

extern PACKAGE bool IsConsole;

Description

The IsConsole variable is true if the module was compiled as a console application. This will be true in both an EXE and in a DLL.


IsLibrary variable

See also

IsLibrary is a bool variable which is true if the module is a DLL.

Unit

System

extern PACKAGE bool IsLibrary;

Description

The IsLibrary variable is true if the module is a DLL.


IsMultiThread variable

See also

IsMultiThread is a bool variable which is set true by the BeginThread function.

Unit

System

extern PACKAGE bool IsMultiThread;

Description

IsMultiThread is set to true by BeginThread in order to allow the memory manager to execute safely if a VCL application has more than one thread. If a second thread attempts to allocate memory, it is blocked until the first thread exits the memory manager.


LeadBytes variable

See also

LeadBytes is a set of all char values that can be the first byte of a double byte character on the local system.

Unit

SysUtils

extern PACKAGE System::Set<char, 0, 255>  LeadBytes;

Description

Use LeadBytes to test whether a char value can represent the lead byte in a double byte character. If an individual char is in the LeadBytes set, it is not necessarily used as the lead byte of a double byte character.  It may also appear as the second byte of a double byte character.  To determine whether the character is used as a lead byte, use the global ByteType or StrByteType function.

Note

LeadBytes is always empty when running on a system with a locale that does not use a multi byte character system (MBCS).


LibModuleList variable

See also

LibModuleList is a linked list of module records used by enumeration routines.

Unit

System

extern PACKAGE TLibModule *LibModuleList;

Description

LibModuleList implements a linked list of records for EXEs and packages in an application. The HINSTANCE fields represent the instance handle of the EXE or package, and the instance handle of the resource associated with that executable instance. LibModuleList is used by the EnumModules and the EnumResourceModules routines.


LongRec type

LongRec stores high- and low-order bytes of a specified variable as a Word.

Unit

SysUtils

struct LongRec

{

Word Lo;

Word Hi;

} ;

Description

LongRec declares a utility record that stores the high- and low-order bytes of the specified variable as type Word.

LongRec is useful for typecasting four-byte datatypes to access their low and high words separately.


MSecsPerDay constant

See also

MSecsPerDay is the number of milliseconds per day.

Unit

SysUtils

#define MSecsPerDay (int)(86400000)

Description

Use MSecsPerDay in calculations that convert between time measured in days and time measured in milliseconds.


Null variable

See also

Null represents the null Variant.

Unit

System

extern PACKAGE Variant Null;

Description

Use Null to indicate unknown or missing data. Null can be assigned to variables in an application that must contain a null value. Assigning Null to a Variant variable does not cause an error, and Null can be returned from any function with a Variant return value.

Assigning Null to a variable of any type other than Variant causes either a compile-time error or raises an EVariantError exception. For example, in the following code the assignment of v, the Null Variant, to Variant q is successful; whereas the conversion of Variant v, which is now Null, to the integer return type of the Test function, raises an exception.

Expressions involving Null always result in Null. Thus, Null is said to “propagate” through intrinsic functions that return Variant data types. If any part of the expression evaluates to Null, the entire expression evaluates to Null.


NullStr constant

NullStr declares a pointer to EmptyStr.

Unit

SysUtils

extern PACKAGE System::AnsiString *NullStr;

Description

NullStr is the return value for many string handling routines when the string is empty.


PEXTENSION_CONTROL_BLOCK type

PEXTENSION_CONTROL_BLOCK is the type of the TISAPIRequest.ECB property.

Unit

Isapiapp

Description

PEXTENSION_CONTROL_BLOCK is the type of the TISAPIRequest::ECB property, which represents the extension control block structure used by the server application DLL to communicate with the web server.


RandSeed variable

See also

RandSeed stores the built-in random number generator's seed.

Unit

System

extern PACKAGE int RandSeed;

Description

By assigning a specific value to RandSeed, the Random function can repetitively generate a specific sequence of random numbers. This is useful for applications that deal with data statistics and simulations. For applications that deal with encryption see the note under the Random function.


Screen variable

See also 	Example

Screen is a TScreen component. It normally represents a screen device.

Unit

Forms

extern PACKAGE TScreen* Screen;

Description

The Screen variable is a TScreen component that represents the screen of the system on which the VCL application runs. By default, applications create a screen component based on information from Windows about the current screen device and assign it to Screen.


SecsPerDay constant

See also

SecsPerDay is the number of seconds per day.

Unit

SysUtils

#define SecsPerDay (int)(86400)

Description

SecsPerDay declares the number of seconds per day.


Session variable

See also

Session maintains database components used by an application.

Unit

DBTables

extern PACKAGE TSession* Session;

Description

Session is responsible for maintaining all of the database components used by an application. It is created automatically as part of an application's initialization and destroyed as part of the application's termination. The Session variable must remain active at all times; it can not be destroyed and recreated.


Sessions variable

See also 	Example

Sessions provides access to TSessionList methods and properties.

Unit

DBTables

extern PACKAGE TSessionList* Sessions;

Description

Sessions is a way to access TSessionList methods and properties for manipulating sessions. The DB unit automatically creates and destroys Sessions for you; you don't need to do anything but use it.

The Session variable, on the other hand, is responsible for maintaining all of the database components used by your application. It is created automatically as part of your application's initialization and destroyed as part of your application's termination. The Session variable must remain active at all times; it can not be destroyed and recreated.


SocketErrorProc variable

See also

SocketErrorProc handles error messages that are received from a Windows socket connection.

Unit

ScktComp

extern THREAD void __fastcall (*SocketErrorProc)(int ErrorCode);

Description

Assign a value to SocketErrorProc to handle error messages from Windows socket API calls before the socket component raises an exception. Setting SocketErrorProc prevents the socket component from raising an exception.

SocketErrorProc is a thread-local variable. It only handles errors that arise from the Windows socket API calls made within a single execution thread.


SystemPalette16 variable

See also

SystemPalette16 contains the 16 VGA system colors.

Unit

graphics

extern PACKAGE HPALETTE SystemPalette16;

Description

SystemPalette16 holds a palette handle which contains the 16 VGA system colors. This palette is built at runtime from the system colors defined by the current video card and driver.  The actual color values of the stock VGA palette can vary from one video card vendor to the next. Therefore it is not safe to assume, for example, that clGray will be RGB(128,128,128) on all systems.

This handle is available as a convenience.  This is the palette that VCL forces on all 16 color bitmaps that are loaded from files or resources.

Note:	Using custom 16-color palettes does not work on 16-color video systems. It is problematic on many 256 color drivers because the variation in colors interferes with transparency operations.


.TActiveFormBorderStyle
TActiveFormBorderStyle type

See also

Specifies the style of an active form's border.

Unit

Forms

enum TActiveFormBorderStyle { afbNone, afbSingle, afbSunken, afbRaised };

Description

The following are possible values for AXBorderStyle:

value	meaning

afbNone	The form has no border.

afbSingle	The form has a regular single-line border.

afbSunken	The form has a 3D look—that is, a border with a sunken edge.

afbRaised	The form has a border with a raised edge.


TBookmark type

See also

TBookmark is a pointer passed to the GetBookmark, GotoBookmark, and FreeBookmark methods.

Unit

DB

typedef void *TBookmark;

Description

TBookmark is the type of the Bookmark parameter you use to call the GetBookmark, GotoBookmark, and FreeBookmark methods of a dataset component.


TEnumModuleFunc type

See also

TEnumModuleFunc is the type of the callback function used in module enumeration.

Unit

System

typedef bool (*TEnumModuleFunc)(HINSTANCE hinstance, void *data);

Description

TEnumModuleFunc is the type of a user-defined callback function passed as a parameter to the EnumModules and the EnumResourceModules routines. TEnumModuleFunc receives an instance handle (HINSTANCE) and a user-defined data value for every module being enumerated. The parameters to TEnumModuleFunc are as follows:

Parameter	Meaning
HInstance	the instance handle of the module being enumerated.
Data	A 32-bit user-defined value passed to the enumeration routine.
To continue enumerating modules, TEnumModuleFunc must return true; to stop enumerating modules, it must return false.


TFormBorderStyle, TBorderStyle types

TFormBorderStyle is the type of the BorderStyle property for Forms and windows.  TBorderStyle is the type of the BorderStyle property for other controls.

Unit

Forms

enum TFormBorderStyle { bsNone, bsSingle, bsSizeable, bsDialog, bsToolWindow, bsSizeToolWin };

typedef TFormBorderStyle TBorderStyle;

Description

These are the possible values of the TFormBorderStyle type:

Value	Meaning
bsNone	No visible border. (not resizeable)
bsSingle	Single-line border. (not resizeable)
bsDialog	Standard dialog box border. (not resizeable)
bsSizeable	Standard resizeable border.
bsToolWindow	Like bsSingle but with a smaller caption.
bsSizeToolWin	Like bsSizeable but with a smaller caption.
Only the bsNone and bsSingle values are possible values of TBorderStyle.


TButtonLayout type

TButtonLayout defines values for the Layout property of TBitBtn or TSpeedButton.

Unit

Buttons

enum TButtonLayout { blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom };

Description

TButtonLayout defines the values the Layout property of a bitmap button (TBitBtn) or speed button (TSpeedButton) can assume. The following table lists the values for TButtonLayout:

Value	Meaning
blGlyphLeft	The image appears near the left side of the button.
blGlyphRight	The image appears near the right side of the button.
blGlyphTop	The image appears near the top of the button.
blGlyphBottom	The image appears near the bottom of the button.


TByteArray type

TByteArray is a general array of type Byte.

Unit

SysUtils

typedef Byte TByteArray[32768];

Description

TByteArray declares a general array of type Byte that can be used in typecasting.


TColor type

TColor is used to specify the color of an object.

Unit

Graphics

enum TColor {clMin=-0x7fffffff-1, clMax=0x7fffffff};

Description

TColor is used to specify the color of an object. It is used by the Color property of many components and by a number of other properties that specify color values.

Graphics contains definitions of useful constants for TColor. These constants map either directly to the closest matching color in the system palette (for example, clBlue maps to blue) or to the corresponding system screen element color defined in the Color section of the Windows Control panel (for example, clBtnFace maps to the system color for button faces).

If you specify TColor as a specific 4-byte hexadecimal number instead of using the constants defined in Graphics, the low three bytes represent RGB color intensities for blue, green, and red, respectively. The value $00FF0000 represents full-intensity, pure blue, $0000FF00 is pure green, and $000000FF is pure red. $00000000 is black and $00FFFFFF is white.

If the highest-order byte is zero ($00), the color obtained is the closest matching color in the system palette. If the highest-order byte is one ($01), the color obtained is the closest matching color in the currently realized palette. If the highest-order byte is two ($02), the value is matched with the nearest color in the logical palette of the current device context.

The following tables lists the color constants from Graphics.  The first two columns list the colors that map to the closest matching color in the system palette, while the last two columns list the colors that are defined in the Windows Control panel.

Value	Meaning	Value	Meaning
clAqua	Aqua	clBackground	Current background color of the Windows desktop
clBlack	Black	clActiveCaption	Current color of the title bar of the active window
clBlue	Blue	clInactiveCaption	Current color of the title bar of inactive windows
clDkGray	Dark Gray	clMenu	Current background color of menus
clFuchsia	Fuchsia	clWindow	Current background color of windows
clGray	Gray	clWindowFrame	Current color of window frames
clGreen	Green	clMenuText	Current color of text on menus
clLime	Lime green	clWindowText	Current color of text in windows
clLtGray	Light Gray	clCaptionText	Current color of the text on the title bar of the active window
clMaroon	Maroon	clActiveBorder	Current border color of the active window
clNavy	Navy blue	clInactiveBorder	Current border color of inactive windows
clOlive	Olive green	clAppWorkSpace	Current color of the application workspace
clPurple	Purple	clHighlight	Current background color of selected text
clRed	Red	clHightlightText	Current color of selected text
clSilver	Silver	clBtnFace	Current color of a button face
clTeal	Teal	clBtnShadow	Current color of a shadow cast by a button
clWhite	White	clGrayText	Current color of text that is dimmed
clYellow	Yellow	clBtnText	Current color of text on a button
		clInactiveCaptionText	Current color of the text on the title bar of an inactive window
		clBtnHighlight	Current color of the highlighting on a button
		cl3DDkShadow	Windows 95 or NT 4.0 only: Dark shadow for three-dimensional display elements
		cl3DLight	Windows 95 or NT 4.0 only: Light color for three-dimensional display elements (for edges facing the light source)
		clInfoText	Windows 95 or NT 4.0 only: Text color for tool tip controls
		clInfoBk	Windows 95 or NT 4.0 only: Background color for tool tip controls


TComponentName type

TComponentName is the type for the Name property for all components.

Unit

Classes

typedef System::AnsiString TComponentName;

Description

TComponentName is the type of the Name property for all components.


TCreateInfo type

See also

TCreateInfo is a record used by TOleContainer's CreateObjectFromInfo method.

Unit

OleCtnrs

struct TCreateInfo

{

TCreateType CreateType;

bool ShowAsIcon;

int IconMetaPict;

GUID ClassID;

System::WideString FileName;

_di_IDataObject DataObject;

} ;

Description

TCreateInfo is a record used by TOleContainer's  CreateObjectFromInfo method. TCreateInfo's fields are  described in the following table:

Fields	Meaning
CreateType	A TCreateType value that describes the source of the object. See TCreateType for details.
ShowAsIcon	Indicates whether the object is shown as an icon (true) or displayed as it would be in the server application false).
IconMetaPict	Specifies a global memory handle to a metafile picture (TMetaFilePict) to display in place of the OLE object's default icon. IconMetaPict is optional; if you set it to 0, the object's default icon will be used (when ShowAsIcon is true).
ClassID	The class identifier of the OLE object you want to create. ClassID is only used when CreateType is ctNewObject. You can use the ProgIDToClassID function to get the class identifier for an OLE object's class name (or programmatic identifier).
FileName	The name of a file to link or embed as an OLE object. FileName is only used when CreateType is ctFromFile or ctLinkToFile.
DataObject	An OLE data transfer object. DataObject is only used when CreateType is ctFromData or ctLinkFromData.


TCreateParams type

See also

TCreateParams is the window-creation parameter record used to specify the type of window to create for a windowed control.

Unit

Controls

struct TCreateParams

{

char *Caption;

int Style;

int ExStyle;

int X;

int Y;

int Width;

int Height;

HWND WndParent;

void *Param;

tagWNDCLASSA WindowClass;

char WinClassName[64];

} ;

Description

The TCreateParams type is a data structure holding information needed when telling Windows to create a window handle. The fields of a TCreateParams record become the parameters to a call to the CreateWindowEx API function.  TCreateParams contains the following fields:

Field	Meaning
Caption	The window caption.  This is usually the value of the Caption or Text property of the control.
Style	The Windows style for the window.  This is a bit array of flags such as WS_CHILD or WS_DISABLED.  See the Microsoft Windows documentation for possible flags.
ExStyle	The extended Windows style for the window. This is one of the Windows predefined extended style constants such as  WS_EX_TOOLWINDOW or WS_EX_CONTROLPARENT.  See the Microsoft Windows documentation for possible values.
X	the x coordinate of the left side of the window.  This is usually the same as the Left property.
Y	the y coordinate of the top of the window.  This is usually the same as the Top property.
Width	the width, in pixels, of the window.  This is usually the same as the Width property.
Height	the height, in pixels, of the window.  This is usually the same as the Height property.
WndParent	the window handle of the parent window.  This is the same as the Handle property of the parent control or, if the Parent property is NULL, the value of ParentWindow.
Param	a pointer to the windows creation parameter that is passed as the LParam of the WM_CREATE message.
WindowClass	the WindowClass record that describes the class of window being created.  The WindowClass record includes information about the window routine, style, default cursor, background brush, associated menus, and so on.
WinClassName	the window class name.  This must be the name of a window class that has already been registered.  Windows provides several built-in window classes with predefined names.  Applications may also register their own custom window classes.


TCreateType type

See also

TCreateType is an enumerated type that defines values for TCreateInfo's CreateType field.

Unit

OleCtnrs

enum TCreateType { ctNewObject, ctFromFile, ctLinkToFile, ctFromData, ctLinkFromData };

Description

TCreateType defines the possible values for TCreateInfo's CreateType field which is passed to TOleContainer's  CreateObjectFromInfo method. Defined as follows:

Values	Meaning
ctNewObject	Creates an embedded OLE object given its class identifier (TCreateInfo.ClassID)
ctFromFile	Creates an embedded OLE object from the contents of the given file (TCreateInfo.FileName).
ctLinkToFile	Creates a linked OLE object from the contents of the given file (TCreateInfo.FileName)
ctFromData	Creates an embedded OLE object from the given data transfer object (TCreateInfo.DataObject)
ctLinkFromData	Creates a linked OLE object from the given data transfer object (TCreateInfo.DataObject)


TDataSetNotifyEvent type

TDataSetNotifyEvent is a pointer to a method used to notify a dataset component an event has occurred.

Unit

DB

typedef void __fastcall (__closure *TDataSetNotifyEvent)(TDataSet* DataSet);

Description

TDataSetNotifyEvent specifies a method that notifies a dataset component when an event has occurred. It is used by all the events of the tables, queries, and stored procedures (TTable, TQuery, and TStoredProc components). The DataSet parameter is the dataset component that is receiving the notification.


TDateTime type

See also

TDateTime is a used by the date and time routines to hold date and time values.

Unit

System

extern PACKAGE TDateTime __fastcall VarToDateTime(const Variant &V);

Description

C++Builder VCL applications store date and time values in the TDateTime type. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is fraction of a 24 hour day that has elapsed.

Following are some examples of TDateTime values and their corresponding dates and times:

0	12/30/1899 12:00 am
2.75	1/1/1900 6:00 pm
-1.25	12/29/1899 6:00 am
35065	1/1/1996 12:00 am
To find the fractional number of days between two dates, simply subtract the two values. Likewise, to increment a date and time value by a certain fractional number of days, simply add the fractional number to the date and time value.


TFieldClass type

TFieldClass is used to create an object reference to TField.

Unit

DB

typedef System::TMetaClass* TFieldClass;

Description

TFieldClass is the object type of TField. Use it to create an object reference to a TField.


TFieldType type

TFieldType is a set of values for the DataType property of TField or TFieldDef.

Unit

DB

enum TFieldType { ftUnknown, ftString, ftSmallint, ftInteger, ftWord, ftBoolean, ftFloat, ftCurrency, ftBCD, ftDate, ftTime, ftDateTime, ftBytes, ftVarBytes, ftAutoInc, ftBlo b, ftMemo, ftGraphic, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary, ftCursor };

Description

TFieldType type is the set of values of the DataType property of a TField component or TFieldDef component. The following table describes each value:

Value	Description
ftUnkown	Unknown or undetermined
ftString	Character or string field
ftSmallint	16-bit integer field
ftInteger	32-bit integer field
ftWord	16-bit unsigned integer field
ftBoolean	Boolean field
ftFloat	Floating-point numeric field
ftCurrency	Money field
ftBCD	Binary-Coded Decimal field
ftDate	Date field
ftTime	Time field
ftDateTime	Date and time field
ftBytes	Fixed number of bytes (binary storage)
ftVarBytes	Variable number of bytes (binary storage)
ftAutoInc	Auto-incrementing 32-bit integer counter field
ftBlob	Binary Large OBject field
ftMemo	Text memo field
ftGraphic	Bitmap field
ftFmtMemo	Formatted text memo field
ftParadoxOle	Paradox OLE field
ftDBaseOle	dBASE OLE field
ftTypedBinary	Typed binary field
ftCursor	Output cursor from an Oracle stored procedure (TParam only)


TFloatFormat type

See also

TFloatFormat is an enumerated list of formatting codes for float functions.

Unit

SysUtils

enum TFloatFormat { ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency };

Description

TFloatFormat defines an enumerated list of formatting codes for the float functions.

Format	Defines
ffGeneral	General number format. The value is converted to the shortest possible decimal string using fixed or scientific format. Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format, and the Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).
ffExponent	Scientific format. The value is converted to a string of the form "-d.ddd...E+dddd". The resulting string starts with a minus sign if the number is negative, and one digit always precedes the decimal point. The total number of digits in the resulting string (including the one before the decimal point) is given by the Precision parameter. The "E" exponent character in the resulting string is always followed by a plus or minus sign and up to four digits. The Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).
ffFixed	Fixed point format. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative, and at least one digit always precedes the decimal point. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18. If the number of digits to the left of the decimal point is greater than the specified precision, the resulting value will use scientific format.
ffNumber	Number format. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The ffNumber format corresponds to the ffFixed format, except that the resulting string contains thousand separators.
ffCurrency	Currency format. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, and DecimalSeparator global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panel. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18.


TFloatRec type

TFloatRec is the result record for FloatToDecimal.

Unit

SysUtils

struct TFloatRec

{

short Exponent;

bool Negative;

char Digits[21];

} ;

Description

TFloatRec is the FloatToDecimal result record.


TFloatValue type

TFloatValue ValueType is the parameter for FloatToText, FloatToTextFmt , TextToFloat and FloatToDecimal.

Unit

SysUtils

enum TFloatValue { fvExtended, fvCurrency };

Description

TFloatValue is the type of the ValueType parameter of the FloatToText, FloatToTextFmt, FloatToDecimal, and TextToFloat functions. The ValueType parameter indicates whether the value being passed to the function is a currency value or a normal floating-point value.

Value	Meaning
fvExtended	The value is a normal floating-point type.
fvCurrency	THe value is a currency type.


TGridDrawState type

TGridDrawState defines the possible states of a cell when drawing occurs.

Unit

Grids

typedef Set<Grids__3, gdSelected, gdFixed>  TGridDrawState;

Description

TGridDrawState defines the possible states of cell when drawing occurs. The TGridDrawState is the type of method parameters used for grid objects. TGridDrawState can represent a value that includes zero or more of the following:

Value	Meaning
gdSelected	The cell in the grid is selected.
gdFocused	The cell in the grid has input focus.
gdFixed	The cell is in the fixed (nonscrolling) region of the grid.


THintInfo type

THintInfo is used to define the appearance and behavior of the Help window.

Unit

Forms

struct THintInfo

{

Controls::TControl* HintControl;

System::TMetaClass*HintWindowClass;

tagPOINT HintPos;

int HintMaxWidth;

Graphics::TColor HintColor;

Windows::TRect CursorRect;

tagPOINT CursorPos;

int ReshowTimeout;

int HideTimeout;

System::AnsiString HintStr;

void *HintData;

};

Description

The THintInfo type is used to define the appearance and behavior of the Help window in a TShowHintEvent type OnShowHint event handler.  The following table describes the meaning of its fields:

Field	Meaning
HintControl	The name of the control for which hint processing is occurring.
HintWindowClass	The class of the hint-window control. The default is THintWindow, but you can specify any class derived from THintWindow. Use this field if you want to substitute a custom hint window for the standard VCL component.
HintPos	The default position in screen coordinates of the top-left corner of the hint window. Change where the window appears by changing this value.
HintMaxWidth	The maximum width of the hint window before word wrapping begins. By default, the value is the width of the screen (Screen.Width).
HintColor	The background color of the Hint window.
CursorRect	The rectangle the user's mouse pointer must be in for the hint window to appear. The default value for CursorRect is the client rectangle of the control. Change this value so that a single control can be divided into several hint regions. When the user moves the mouse pointer outside the rectangle, the hint window disappears.
CursorPos	The location of the mouse pointer within the control.
ReshowTimeout	How long the hint system should wait before asking about the hint status again. By default, this field is zero, indicating that the hint status will not change. Setting it to a non-zero value will cause the hint to act, after the requested milliseconds have elapsed, as if the user moved the mouse outside the hint rectangle and back in. This can be used to either put off hint processing for a period of time, or to allow the hint to be updated periodically.
HideTimeout	The number of milliseconds to show the hint. It is set to Application.HintHidePause by default.
HintStr	The string to be displayed in the hint window. This allows an OnHint event handler to modify the contents of a hint before it is displayed. By default it contains the value of the following expression: GetShortHint(Application.Hint).
HintData	Additional data to be passed to the hint-window control. Use this field in conjunction with HintWindowClass.


TIdentToInt type

See also

IdentToInt is a pointer to a function that converts a text identifier to an integer value.

Unit

classes

typedef bool __fastcall (*TIdentToInt)(const System::AnsiString Ident, int &Int);

Description

IdentToInt is the type of a function pointer that is used in the streaming system to convert text identifiers in the stream to their integer values.. This function can be used by component writers to define their own named integer values.  The Ident parameter specifies a AnsiString identifier that stands for a numeric type value.  The Int parameter is used to return the corresponding integer value.  The return value indicates whether the identifier was successfully converted into an integer.

Note:	For more information about defining and using these types of functions, refer to the implementation of RegisterIntegerConsts in the Classes unit, and ColorToIdent, IdentToColor, CharsetToIdent, and IdentToCharset in the Graphics unit.


TIntToIdent type

See also

IdentToInt is a pointer to a function that converts an integer to a  text identifier.

Unit

classes

typedef bool __fastcall (*TIntToIdent)(int Int, System::AnsiString &Ident);

Description

IntToIdent is the type of a function pointer that is used in the streaming system to convert integer values to text identifiers when saving property values. This function can be used by component writers to define their own named integer values.  The Int parameter specifies a integer type value.  The Ident parameter is used to return the corresponding AnsiString identifier.  The return value indicates whether the integer was successfully converted into an AnsiString.

Note:	For more information about defining and using these types of functions, refer to the implementation of RegisterIntegerConsts in the Classes unit, and ColorToIdent, IdentToColor, CharsetToIdent, and IdentToCharset in the Graphics unit.


TLocale type

TLocale is the  type for the Locale or DBLocale property.  It is used for direct calls to BDE.

Unit

DBTables

typedef void *TLocale;

Description

The TLocale type is the type of a Locale or DBLocale property. These properties are only used or needed when making direct calls to the Borland Database Engine.

Note

Do not confuse TLocale with the TSysLocale type that represents a Windows Locale.  TLocale is specific to the Borland Database Engine.


TLocateOptions type

TLocateOptions defines the values for the Options parameter of the Locate method of TTable, TQuery, and TStoredProc.

Unit

DB

typedef Set<TLocateOption, loCaseInsensitive, loPartialKey>  TLocateOptions;

Description

The TLocateOptions type defines the possible values for the Options parameter of the Locate method of the TTable, TQuery, and TStoredProc components, as described in the following table:

Value	Description
loCaseInsensitive	Key fields and key values are matched without regard to case.
loPartialKey	Key values can include only part of the matching key field value; for example, 'HAM' would match both 'HAMM' and 'HAMMER.'


TMbcsByteType type

See also

TMbcsByteType represents the use of a single byte char in a string that uses a multi byte character set (MBCS).

Unit

SysUtils

enum TMbcsByteType { mbSingleByte, mbLeadByte, mbTrailByte };

Description

TMbcsByteType represents the possible return values of the ByteType and StrByteType functions.  Possible values are as follows:

Values	Meaning
mbSingleByte	The char is used to represent an entire character in the string. The value of char can not be included in the LeadBytes set.
mbLeadByte	The char is used to represent the first byte of a double byte character.  The value of char must be included in the LeadBytes set.
mbTrailByte	The char is used to represent the second byte of a double byte character. There are no a priori restrictions on the value of char.


TMessage type

TMessage is the type of the parameter passed to the WndProc method.

Unit

Messages

struct TMessage

{

Cardinal Msg;

union

{

struct

{

Word WParamLo;

Word WParamHi;

Word LParamLo;

Word LParamHi;

Word ResultLo;

Word ResultHi;

};

struct

{

int WParam;

int LParam;

int Result;

};

};

} ;

Description

The TMessage type represents a Windows message in WndProc and other methods.


TMethod type

TMethod is a record used to store Code and Data fields as type void*.

Unit

SysUtils

struct TMethod

{

void *Code;

void *Data;

};

Description

The TMethod type declares a record that stores the Code and Data fields as type void*.

This type can be used in a type cast of a method pointer to access the code and data parts of the method pointer.


TMouseButton type

See also

TMouseButton defines the mouse-button constants used by mouse-event handlers.

Unit

Controls

enum TMouseButton { mbLeft, mbRight, mbMiddle };

Description

The TMouseButton type defines the mouse-button constants used by mouse-event handlers to distinguish which button generated the mouse event.


TMsgDlgButtons type

TMsgDlgButtons defines a set of values used by MessageDlg and MessageDlgPos.

Unit

Dialogs

typedef Set<TMsgDlgBtn, mbYes, mbHelp>  TMsgDlgButtons;

Description

The TMsgDlgButtons type defines the set of values a button in a message box can have. The TMsgDlgButtons type is used by the MessageDlg and MessageDlgPos functions. The following tables lists the possible values:

Value	Meaning
mbYes	A button with a green check mark and the text 'Yes' on its face
mbNo	A button with a red circle and slash mark through the circle and the text 'No' on its face
mbOK	A button with a green check mark and the text 'OK' on its face
mbCancel	A button with a red X and the text 'Cancel' on its face
mbHelp	A button with a cyan question mark and the text 'Help' on its face
mbAbort	A button with a red check mark and the text 'Abort' on its face
mbRetry	A button with two green circular arrows and the text 'Retry' on its face
mbIgnore	A button with a green man walking away and the text 'Ignore' on its face
mbAll	A button with a green double check marks and the text 'All' on its face


TMsgDlgType type

TMsgDlgType defines values describing the type of message box.

Unit

Dialogs

enum TMsgDlgType { mtWarning, mtError, mtInformation, mtConfirmation, mtCustom };

Description

The TMsgDlgType type defines the values describing the type of message box. The TMsgDlgType is used by the MessageDlg and MessageDlgPos functions. The following table lists the possible values:

Value	Meaning
mtWarning	A message box containing a yellow exclamation point symbol.
mtError	A message box containing a red stop sign.
mtInformation	A message box containing a blue "i".
mtConfirmation	A message box containing a green question mark.
mtCustom	A message box containing no bitmap. The caption of the message box is the name of the application's executable file.


TNotifyEvent type

TNotifyEvent is used for events that do not require parameters.

Unit

Classes

typedef void __fastcall (__closure *TNotifyEvent)(System::TObject* Sender);

Description

The TNotifyEvent type is the type for events that have no event-specific parameters. These events simply notify the component that a specific event occurred. For example, OnClick, which is of type TNotifyEvent, notifies the control that a click event occurred on the control.  The Sender paramter is the object that receives the notification.

The Sender parameter is the object whose event handler is called.  For example,.with the OnClick event of a button, the Sender parameter is the button component that is clicked.


TOperation type

See also

TOperation represents the types of operations whose occurrence is broadcast by the Notification method.

Unit

Classes

enum TOperation { opInsert, opRemove };

Description

The TOperation type is used in the Notification method to indicate whether the notification indicates the creation or deletion of an object. The following table gives the possible values:

Value	Meaning
opInsert	The specified object has just been created.
opRemove	The specified object has been destroyed, and its memory is about to be freed.


TPackageInfoProc type

See also

TPackageInfoProc is a pointer to a callback function used as a parameter type to the GetPackageInfo routine.

Unit

SysUtils

typedef void __fastcall (*TPackageInfoProc)(const System::AnsiString Name, TNameType NameType, Byte Flags, void * Param);

Description

TPackageInfoProc is the type of the callback given to the GetPackageInfo routine.  The callback function is called for every element in the package.  Name is the name of the package element for a specific call.  Depending on the value of the NameType parameter, it is either the name of a unit contained in the package or the name of another package that is required by the package.  Flags are the flags listed in the information table for the package. Param is a user-defined value passed to GetPackageInfo. TNameType is the type of the NameType parameter of the TPackageInfoProc type. The following table lists the values of TNameType:

Value	Meaning
ntContainsUnit	The Name parameter is a unit contained in the package.
ntRequiresPackage	The Name parameter is another package required by the package.


TPaymentTime type

TPaymentTime is an enumerated type used as a parameter in financial functions.

Unit

Math

enum TPaymentTime { ptEndOfPeriod, ptStartOfPeriod };

Description

TPaymentTime is an enumerated type used as a parameter in many of the financial functions. The following table lists the possible values:

Value	Meaning
ptStartOfPeriod	Interest is calculated on the principle balance at the beginning of the payment period
ptEndOfPeriod	Interest is calculated at the end of the payment period


TPoint type

TPoint type defines a pixel location onscreen.

Unit

Windows

typedef tagPOINT  TPoint;

Description

The TPoint type defines a pixel location onscreen, with the origin in the top left corner. X specifies the horizontal coordinate of the point, Y specifies the vertical coordinate.


TProcedure type

TProcedure is used as the type for generic routines that do not have arguments.

Unit

SysUtils

typedef void __fastcall (*TProcedure)(void);

Description

The TProcedure is used as the type for parameters to many routines when the function being passed in does not take any arguments.


TRect type

TRect type defines a rectangle.

Unit

Windows

struct TRect

  {

          TRect() {}

          TRect(RECT& r)

          {

                  Left    = r.left;

                  Top     = r.top;

                  Right   = r.right;

                  Bottom  = r.bottom;

          }

          operator RECT()

          {

                  RECT r;

                  r.left     = Left;

                  r.top      = Top;

                  r.right    = Right;

                  r.bottom   = Bottom;

                  return r;

          }

          union

          {

                  struct

                  {

                          POINT TopLeft;

                          POINT BottomRight;

                  };

                  struct

                  {

                          int Left;

                          int Top;

                          int Right;

                          int Bottom;

                  };

          };

  };

Description

The coordinates are specified either as four separate integers representing the pixel locations of the left, top, right, and bottom sides, or as two points representing the pixel locations of the top left and bottom right corners. The origin of the pixel coordinate system is in the top left corner of the screen.


TResType type

TResType specifies a type of graphical resource to ImageList.

Unit

Controls

enum TResType { rtBitmap, rtCursor, rtIcon };

Description

TResTypes is used by the image list methods ResourceLoad, GetResource and FileLoad to specify the type of graphical resource that is to be loaded or retrieved from the ImageList

Value	Meaning
rtBitmap	Loads or retrieves a bitmap
rtCursor	Loads or retrieves a cursor
rtIcon	Loads or retrieves an icon


TSearchRec type

TSearchRec defines file information searched for by FindFirst or FindNext.

Unit

SysUtils

struct TSearchRec

{

int Time;

int Size;

int Attr;

System::AnsiString Name;

int ExcludeAttr;

int FindHandle;

_WIN32_FIND_DATAA FindData;

} ;

Description

The TSearchRec type defines file information searched for by a FindFirst or FindNext function call. If a file is found, the fields of the TSearchRec type parameter are modified to specify the found file.

Attr represents the file attributes the file attributes of the file. Test Attr against the following attribute constants or values to determine if a file has a specific attribute:

Constant	Value	Description
faReadOnly	$00000001	Read-only files
faHidden	$00000002	Hidden files
faSysFile	$00000004	System files
faVolumeID	$00000008	Volume ID files
faDirectory	$00000010	Directory files
faArchive	$00000020	Archive files
faAnyFile	$0000003F	Any file
To test for an attribute, combine the value of the Attr field with the attribute constant with the and operator. If the file has that attribute, the result will be greater than 0. For example, if the found file is a hidden file, the following expression will evaluate to true: (SearchRec.Attr and faHidden > 0).

Time contains the time stamp of the file. Size contains the size of the file in bytes. Name contains the DOS file name and extension.  FindData contains additional information such as the file creation time, last access time, and both the long and short file names.


TShiftState type

See also

TShiftState indicates the state of the Alt, Ctrl, and Shift keys and the mouse buttons.

Unit

Classes

typedef Set<Classes__1, ssShift, ssDouble>  TShiftState;

Description

The TShiftState type is used by key-event and mouse-event handlers to determine the state of the Alt, Ctrl, and Shift keys and the state of the mouse buttons when the event occurred.  It is a set of flags that indicate the following:

Value	Meaning
ssShift	The Shift key is held down.
ssAlt	The Alt key is held down.
ssCtrl	The Ctrl key is held down.
ssLeft	The left mouse button is held down.
ssMiddle	The middle mouse button is held down.
ssDouble	The mouse was double-clicked.


TShortCut type

TShortCut represents a menu shortcut.

Unit

Menus

typedef Word TShortCut;

Description

TShortCut types are the menu shortcuts that appear on menus and give the user an alternate way to select menu commands using the keyboard. The ShortCut property is of type TShortCut, and the ShortCutToText and ShortCutToKey routines use parameters of type TShortCut. TShortCut is also the return type of the TextToShortCut routine.


TSystemTime type

See also

TSystemTime is the type used to represent date-time values in Windows 32 API function calls.

Unit

Windows

typedef _SYSTEMTIME  TSystemTime;

Description

Use TSystemTime to represent SYSTEMTIME values when making Windows 32 API function calls. Use the DateTimeToSystemTime and SystemTimeToDateTime functions to convert between TSystemTime values and VCL TDateTime values.


TThreadFunc type

TThreadFunc is a pointer to the starting address of a routine for a new thread of execution.

Unit

SysDefs

typedef Integer __fastcall (*TThreadFunc)(Pointer Parameter);

Description

The TThreadFunc type defines a type of routine that is the starting address for a new thread of execution. A TThreadFunc routine is passed to the VCL routine BeginThread or the Windows API CreateThread function. When BeginThread executes, TThreadFunc acts as the entry point for the new thread.

The Parameter pointer passed to the TThreadFunc routine is passed directly to BeginThread. Parameter can be a single 32-bit value or a 32-bit pointer to other data. The value in Parameter can be used within the TThreadFunc routine.

TThreadFunc returns the value of the thread entry point function. This result is usually passed to the EndThread routine. An application can retrieve the TThreadFunc return value by calling the Windows API GetExitCodeThread function.


TTimeStamp type

See also

TTimeStamp represents time and date values.

Unit

SysUtils

struct TTimeStamp

{

int Time;

int Date;

} ;

Description

Use TTimeStamp to represent date and time values when a great deal of accuracy is required for the time portion.  When the time values do not need to be precise to the millisecond, use the more compact TDateTime representation.

TTimeStamp is a record with a Time field that represents the number of seconds elapsed since midnight, and a Date field that represents the number of calendar days since the start of the calendar.


TTypeData type

See also

TTypeData represents class members in various TFormDesigner methods.

Unit

TypeInfo

Description

A TTypeData structure represents a category of properties, events, or methods in parameters passed to several methods of TFormDesigner. The methods that use TTypeData include CreateMethod, GetComponentNames, GetMethods, and GetObjectNames.


TUpdateKind type

TUpdateKind defines the values for the UpdateKind parameter of  the OnUpdateError and OnUpdateRecord events of TTable, TQuery, and TStoredProc.

Unit

DB

enum TUpdateKind { ukModify, ukInsert, ukDelete };

Description

The TUpdateKind type defines the possible values for the UpdateKind parameter of the OnUpdateError and OnUpdateRecord events of the TTable, TQuery, and TStoredProc components, as described in the following table:

Value	Description
ukModify	The cached update to the record is a modification to the record's contents.
ukInsert	The cached update is the insertion of a new record.
ukDelete	The cached update is the deletion of a record.


TVarRec type

TVarRec is used inside a function with a parameter type of array of const.

Unit

Sysdefs

class TVarRec;

typedef TVarRec* PVarRec;

class TVarRec

{

  public:

    union

    {

      Integer      VInteger;

      Boolean      VBoolean;

      Char         VChar;

      PExtended    VExtended;

      PShortString VString;

      Pointer      VPointer;

      PChar        VPChar;

      TObject*     VObject;

      TClass       VClass;

      WideChar     VWideChar;

      PWideChar    VPWideChar;

      Pointer      VAnsiString;

      PCurrency    VCurrency;

      PVariant     VVariant;

    };

    union

    {

      Byte VType;

      long ForceAlignment;

};

Description

TVarRec type is used inside a function with a parameter type of array of const. The VType field lets the function know the simple type of each parameter passed in the open array.

The variable type constants represent the values passed in the tag of the TVarRec structure.

A variable of this type can be created with the ARRAYOFCONST macro. This macro is defined in the sysdefs.h file.


TValueType type

See also

TValueType defines the kinds of values written to and read from filer objects.

enum TValueType { vaNull, vaList, vaInt8, vaInt16, vaInt32, vaExtended, vaString, vaIdent, vaFalse, vaTrue, vaBinary, vaSet, vaLString, vaNil, vaCollection };

Description

TValueType is the type used by the TReader and TWriter filer objects to type- check property values that are read from and written to streams when streaming components and their properties.

Delphi's filers use a tagged value system, where each value on the stream is preceded by a prefix indicating its type. Those prefixes are of type TValueType. The following table lists the values for TValueType:

Value	Meaning

vaNull	identifies the type as the const Variant Null.

vaList	identifies the type as a list of tagged items ending with a NULL pointer.

vaInt8	identifies the type as a Shortint.

vaInt16	identifies the type as a Smallint.

vaInt32	identifies the type as a Lonint.

vaExtended	identifies the type as a float.

vaString	identifies the type as a short string

vaIdent	identifies the type as a VCL identifier string.

vaFalse	identifies the type as the bool false.

vaTrue	identifies the type as the bool true.

vaBinary	identifies the type as a block of binary proceeded by a length count.

vaSet	identifies the type as a set.

vaLString	identifies the type as a AnsiString.

vaNil	identifies the type as NULL.

vaCollection	identifies the type as a TCollection.


TWordArray type

TWordArray declares a general array of type Word.

Unit

SysUtils

typedef Word TWordArray[16384];

Description

TWordArray declares a general array of type Word that can be used in typecasting.


Unassigned constant

See also 	Example

Unassigned is the constant used for a Variant variable not yet assigned a value.

Unit

System

extern PACKAGE Variant Unassigned;

Description

The Unassigned constant is used to indicate that a Variant variable has not yet been assigned a value. The initial value of any Variant variable is Unassigned. The Unassigned value disappears as soon as a Variant variable is assigned any other value, including the value 0, a zero-length string, and the Null value.

Using an Unassigned Variant in an expression causes an EVariantError exception to be raised. Likewise, if you attempt to convert an Unassigned Variant to another type (using VarAsType or VarCast), an EVariantError exception is raised.

You can make a Variant variable unassigned by assigning the Unassigned constant to it. This is particularly useful in situations where a Variant contains a reference to an OLE Automation Object, thus keeping the object "alive" until another value is assigned to the Variant.

Do not use Unassigned to test whether a Variant value is Unassigned. Instead, use the VarIsEmpty standard function. When used on an unassigned Variant, the VarType standard function returns varEmpty.


Win32Platform variable

Win32Platform is the Win32 platform identifier.

Unit

SysUtils

extern PACKAGE int Win32Platform;

Description

Win32Platform is used to identify the type of Win32 platform the system is running. This will be one of the following values:

Value	Meaning
VER_PLATFORM_WIN32s	System is Win32s.
VER_PLATFORM_WIN32_WINDOWS	System is Windows 95.
VER_PLATFORM_WIN32_NT	System is Windows NT.
See WINDOWS.PAS for their associated numerical values.


WordRec type

WordRec declares a utility record to store high and low order bytes of a variable.

Unit

SysUtils

struct WordRec

{

Byte Lo;

Byte Hi;

};

Description

The WordRec type declares a utility record that stores the high and low order bytes of the specified variable as type Byte. WordRec is used primarily for typecasting.


Table of Delphi data types

Delphi	Size/Values	C++ implementation	Implementation

ShortInt	8-bit integer	signed char	typedef

SmallInt	16-bit integer	short	typedef

LongInt	32-bit integer	int	typedef

Byte	8-bit unsigned integer	unsigned char	typedef

Word	16-bit unsigned integer	unsigned short	typedef

Integer	32-bit integer	int	typedef

Cardinal	32-bit unsigned integer	unsigned int	typedef

Boolean	true/false	bool	typedef

ByteBool	true/false or 8-bit unsigned integer	unsigned char	typedef

WordBool	true/false or 16-bit unsigned integer	unsigned short	typedef

LongBool	true/false or 32-bit unsigned integer	BOOL (WinAPI)	typedef

AnsiChar	8-bit unsigned character	char	typedef

WideChar	word-sized Unicode character	wchar_t	typedef

Char	8-bit unsigned character	char	typedef

AnsiString	Delphi AnsiString	AnsiString	class

String[n]	old style Delphi string, n = 1..255 bytes	SmallString<n>	template class

ShortString	old style Delphi string, 255 bytes	SmallString<255>	typedef

String	Delphi AnsiString	AnsiString	typedef

Single	32-bit floating point number	float	typedef

Double	64-bit floating point number	double	typedef

Extended	80-bit floating point number	long double	typedef

Real	32-bit floating point number	double	typedef

Pointer	32-bit generic pointer	void *	typedef

PChar	32-bit pointer to characters	unsigned char *	typedef

PAnsiChar	32-bit pointer to ANSI characters	unsigned char *	typedef

Comp	64-bit floating point number	Comp	class

String[n]	old style Delphi string	SmallString<n>	template class

OleVariant	OLE variant value	OleVariant	class


ChangeFileExt Example

The following function changes the extension of a filename to .INI:

AnsiString __fastcall TForm1::ChangeFileExtToINI(AnsiString as)

{

  return (ChangeFileExt(as, ".INI"));

}

Here’s a line of code that calls the function:

Application->MessageBox(ChangeFileExtToINI("Test").c_str(), "ChangeFileExt example", IDOK);


ColorToRGB Example

The following line converts the color of the current form, Form1, to a Windows RGB value:

DWORD  L = ColorToRGB(Form1->Color);


CompareStr_Example
CompareStr Example

The following code compares String1, 'STEVE', to String2, 'STEVe'. Note that CompareStr returns a number less than 0 because the value of 'e' is greater than the value of 'E'.

AnsiString String1 = "STEVE";

AnsiString String2 = "Steve";

int I = CompareStr(String1, String2);  // the value of I is < 0

if (I != 0)

  ShowMessage ("The strings are not equal");


CompareText Example

The following code compares String1, 'ABC, to String2, 'aaa'. Because CompareText is case insensitive, String2 is larger.

AnsiString String1 = "ABC";

AnsiString String2 = "aaa";

int I = CompareText(String1, String2);  // I < 0

if (I < 0)

  ShowMessage ("String 1 is smaller")

else if (I == 0)

  ShowMessage ("The strings are equal")

else  // I > 0

  ShowMessage ("String 2 is smaller")


Items, Selected Example

for (int i = 0; i < FileListBox1->Items->Count; i++)

{

  if (FileListBox1->Selected[i])

  {

    if (!FileExists(FileListBox1->Items->Strings[i]))

    {

      MessageBeep(0);

      if (Application->MessageBox(AnsiString("File ") + FileListBox1->Items->Strings[i] + " not found",NULL, MB_OKCANCEL | MB_DEFBUTTON1) == IDCANCEL)

        break;

      else

        continue;

    }

    FILE *F = fopen(FileListBox1->Items->Strings[i].c_str(),"r");

    struct stat statbuf;

    fstat(fileno(F), &statbuf);

    ListBox1->Items->Add(IntToStr(statbuf.st_size));

    fclose(F);

  }

}


Date Example
Date, DateToStr Example

This example uses a label and a button on a form. When the user clicks the button, the current date is displayed in the caption of the label:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = DateToStr(Date());

}


DateTimeToStr Example
Now, DateTimeToStr Example

This example uses a label and a button on a form. When the user clicks the button, the current date and time is converted to a string and displayed as the caption of the label:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = DateTimeToStr(Now());

}


DayOfWeek Example

This example uses a button, an edit box, and a label on a form. When the user enters a date in the edit box using the Month/Day/Year format, the caption of the label reports the day of the week for the specified date.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TDateTime dt;

  try

  {

    dt = StrToDate(Edit1->Text);

    Label1->Caption = IntToStr(DayOfWeek(dt));

  }

  catch(...)

  {

    Application->MessageBox("You must enter a date in the Month/Day/Year format.", "Invalid Date", MB_OK);

    Edit1->Clear();

  }

}


DecodeDate Example
DecodeDate, DecodeTime Example

This example uses a button and two labels on a form. When the user clicks the button, the current date and time are reported in the captions of the two labels.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Word Year, Month, Day, Hour, Min, Sec, MSec;

  TDateTime dtPresent = Now();

  DecodeDate(dtPresent, Year, Month, Day);

  Label1->Caption = AnsiString("Today is Day ") + IntToStr(Day) + AnsiString(" of Month ") + IntToStr(Month) + AnsiString(" of Year ") + IntToStr(Year);

  DecodeTime(dtPresent, Hour, Min, Sec, MSec);

  Label2->Caption = AnsiString("The time is Minute ") + IntToStr(Min) + AnsiString(" of Hour ") + IntToStr(Hour);

}


AnsiString::Delete Example

AnsiString s = "Honest Abe Lincoln";

s.Delete(8,4);

Canvas->TextOut(10, 10, s); // "Honest Lincoln"


DiskFree Example
DiskFree, DiskSize Example

AnsiString S;

int AmtFree = DiskFree(0);

int Total = DiskSize(0);

S = IntToStr(AmtFree/Total) + " percent of the space on drive 0 is free: " (AmtFree/1024) + " Kbytes free. ";

Label1->Text = S;


EncodeDate Example

This example uses three edit controls, a label, and a button on a form. When the button is clicked, the day, month, and year specified in the edit controls is stored in a TDateTime object. Then the TDateTime object is converted to an AnsiString that is displayed in the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TDateTime dt;

  try

  {

    dt = EncodeDate((Word)StrToInt(Edit1->Text), (Word)StrToInt(Edit2->Text), (Word)StrToInt(Edit3->Text));

    Label1->Caption = DateToStr(dt);

  }

  catch(...)

  {

    Application->MessageBox("Invalid day, month, or year.", "EncodeDate Example", MB_OK);

  }

}


EncodeTime Example

This example uses four edit controls, a label, and a button on a form. When the button is clicked, the hour, minute, second, and millisecond specified in the edit controls is stored in a TDateTime object. Then the TDateTime object is converted to an AnsiString that is displayed in the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TDateTime dt;

  try

  {

    dt = EncodeTime((Word)StrToInt(Edit1->Text), (Word)StrToInt(Edit2->Text), (Word)StrToInt(Edit3->Text), (Word)StrToInt(Edit4->Text));

    Label1->Caption = TimeToStr(dt);

  }

  catch(...)

  {

    Application->MessageBox("Invalid hour, minute, second, or millisecond.", "EncodeTime Example", MB_OK);

  }

}


TOpenDialog::Title, TOpenDialog::FileName, DeleteFile Example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  OpenDialog1->Title = "Delete File";

  if (OpenDialog1->Execute())

  {

    if (FileExists(OpenDialog1->FileName))

      DeleteFile(OpenDialog1->FileName);

  }

}


ExpandFileName Example

The following example uses a listbox, an edit control, and a button on a form. When the button is clicked, the filename specified in the edit control is expanded to a fully qualified filename and added to the list box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Add(ExpandFileName(Edit1->Text));

}


FileExists, RenameFile, FileCreate, FileWrite, FileClose Example

The following example uses a button, a string grid, and a Save dialog box on a form. When the button is clicked, the user is prompted for a filename. When the user clicks OK, the contents of the string grid are written to the specified file. Additional information is also written to the file so that it can be read easily with the FileRead function.

#include <dir.h>

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char szFileName[MAXFILE+4];

  int iFileHandle;

  int iLength;

  if (SaveDialog1->Execute())

  {

    if (FileExists(SaveDialog1->FileName))

    {

      fnsplit(SaveDialog1->FileName.c_str(), 0, 0, szFileName, 0);

      strcat(szFileName, ".BAK");

      RenameFile(SaveDialog1->FileName, szFileName);

    }

    iFileHandle = FileCreate(SaveDialog1->FileName);

    // Write out the number of rows and columns in the grid.

    FileWrite(iFileHandle, (char*)&(StringGrid1->ColCount), sizeof(StringGrid1->ColCount));

    FileWrite(iFileHandle, (char*)&(StringGrid1->RowCount), sizeof(StringGrid1->RowCount));

    for (int x=0;x<StringGrid1->ColCount;x++)

    {

      for (int y=0;y<StringGrid1->RowCount;y++)

      {

        // Write out the length of each string, followed by the string itself.

        iLength = StringGrid1->Cells[x][y].Length();

        FileWrite(iFileHandle, (char*)&iLength, sizeof(iLength));

        FileWrite(iFileHandle, StringGrid1->Cells[x][y].c_str(), StringGrid1->Cells[x][y].Length());

      }

    }

    FileClose(iFileHandle);

  }

}


FileOpen, FileSeek, FileRead Example

The following example uses a button, a string grid, and an Open dialog box on a form. When the button is clicked, the user is prompted for a filename. When the user clicks OK, the specified file is opened, read into a buffer, and closed. Then the buffer is displayed in two columns of the string grid. The first column contains the character values in the buffer. The second column contains the numeric values of the characters in the buffer.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int iFileHandle;

  int iFileLength;

  int iBytesRead;

  char *pszBuffer;

  if (OpenDialog1->Execute())

  {

    try

    {

      iFileHandle = FileOpen(OpenDialog1->FileName, fmOpenRead);

      iFileLength = FileSeek(iFileHandle,0,2);

      FileSeek(iFileHandle,0,0);

      pszBuffer = new char[iFileLength+1];

      iBytesRead = FileRead(iFileHandle, pszBuffer, iFileLength);

      FileClose(iFileHandle);

      for (int i=0;i<iBytesRead;i++)

      {

        StringGrid1->RowCount += 1;

        StringGrid1->Cells[1][i+1] = pszBuffer[i];

        StringGrid1->Cells[2][i+1] = IntToStr((int)pszBuffer[i]);

      }

      delete [] pszBuffer;

    }

    catch(...)

    {

      Application->MessageBox("Can't perform one of the following file operations: Open, Seek, Read, Close.", "File Error", IDOK);

    }

  }

}


FileSearch Example

The following example uses and edit control and a button on a form. When the button is clicked, the current directory and the Windows directory are searched for the filename specified in the edit control. A message box indicates whether or not the file is found.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char buffer[256];

  GetWindowsDirectory(buffer, sizeof(buffer));

  AnsiString asFileName = FileSearch(Edit1->Text, GetCurrentDir() + AnsiString(";") + AnsiString(buffer));

  if (asFileName.IsEmpty())

    ShowMessage(AnsiString("Couldn't find ") + Edit1->Text + ".");

  else

    ShowMessage(AnsiString("Found ") + asFileName + ".");

}


FindFirst, FindNext, FindClose Example

The following example uses an edit control, a button, a string grid, and seven check boxes. The check boxes correspond to the seven possible file attributes. When the button is clicked, the path specified in the edit control is searched for files matching the checked file attributes. The names and sizes of the matching files are inserted into the string grid.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TSearchRec sr;

  int iAttributes = 0;

  StringGrid1->RowCount = 1;

  iAttributes |= faReadOnly * CheckBox1->Checked | faHidden * CheckBox2->Checked | faSysFile * CheckBox3->Checked | faVolumeID * CheckBox4->Checked | faDirectory * CheckBox5->Checked | faArchive * CheckBox6->Checked | faAnyFile * CheckBox7->Checked;

  if (FindFirst(Edit1->Text, iAttributes, sr) == 0)

  {

    if (sr.Attr == iAttributes)

    {

      StringGrid1->Cells[1][StringGrid1->RowCount-1] = sr.Name;

      StringGrid1->Cells[2][StringGrid1->RowCount-1] = IntToStr(sr.Size);

    }

    while (FindNext(sr) == 0)

    {

      if (sr.Attr == iAttributes)

      {

        StringGrid1->RowCount += 1;

        StringGrid1->Cells[1][StringGrid1->RowCount-1] = sr.Name;

        StringGrid1->Cells[2][StringGrid1->RowCount-1] = IntToStr(sr.Size);

      }

    }

  }

  FindClose(sr);

}


ForceDirectories, DirectoryExists Example

This example uses a label and a button on a form. When the user clicks the button, all the directories along the specified path that don't exist are created. The results are reported in the caption of the label:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  AnsiString Dir = "C:\Apps\Sales\Local";

  ForceDirectories(Dir);

  if (DirectoryExists(Dir))

    Label1->Caption = Dir + " was created";

}


FormatDateTime Example

The following example assigns "The meeting is on Wednesday, February 15, 1995 at 10:30 AM'" to the string variable S.

S = AnsiString("The meeting is on ") + FormatDateTime("dddd, mmmm d, yyyy ' at ' hh:mm AM/PM", StrToDateTime("2/15/95 10:30am"));


FormatFloat Example

The following table shows some sample formats and the results produced when the formats are applied to different values:

Format string-	1234	-1234	0.5	0
	1234	-1234	0.5	0
0	1234	-1234	1	0
0.00	1234.00	-1234.00	0.50	0.00
#.##	1234	-1234	.5
#,##0.00	1,234.00	-1,234.00	0.50	0.00
#,##0.00;(#,##0.00)	1,234.00	(1,234.00)	0.50	0.00
#,##0.00;;Zero	1,234.00	-1,234.00	0.50	Zero
0.000E+00	1.234E+03	-1.234E+03	5.000E-01	0.000E+00
#.###E-0	1.234E3	-1.234E3	5E-1	0E0


GetCharsetValues Example

The following uses the GetCharsetValues procedure to fill a string list with the names of all the character set constants provided by Delphi.  This string list can then be used to allow the user to select a character set.

Here is the callback that adds the character sets to the string list:

void AddCharacterSet(AnsiString S)

{

  CharSetList->Add(S);

}

Here is the code that creates the string list, fills it, and sorts the character set names.

CharSetList = new TStringList();

GetCharSetValues(AddCharacterSet);

CharSetList->Sort();


GetClass Example

The following example allows users to type the name of a graphics class into an edit control and when a button is pressed, the name of the default extension for that class is displayed in another edit control.

// in the form’s OnCreate event handler (or a similar place)

// you must register the graphics classes so that GetClass

// can find them

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TMetaClass *MetaClass = __classid(TIcon);

  RegisterClasses(&MetaClass, 0);

  MetaClass = __classid(Graphics::TBitmap);

  RegisterClasses(&MetaClass, 0);

  MetaClass = __classid(TJPEGImage);

  RegisterClasses(&MetaClass, 0);

  MetaClass = __classid(TMetafile);

  RegisterClasses(&MetaClass, 0);

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Edit2->Text = GraphicExtension((TGraphicClass) GetClass(Edit1->Text));

}


GetShortHint Example

This code assigns a two-part string as to the Hint property of an edit box and then displays the "short" or first part of the string as the text of the edit box:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Edit1->Hint = "Name|Enter full name";

  Edit1->Text = GetShortHint(Edit1->Hint);

}


GraphicExtension Example
GraphicExtension, GraphicFilter, DefaultExt, Filter Example

This code displays a Save Picture dialog box with the TBitmap default extension that is added automatically to files that are given no extension:

SavePictureDialog1->DefaultExt = GraphicExtension(__classid(Graphics::TBitmap));

SavePictureDialog1->Filter = GraphicFilter(__classid(Graphics::TBitmap));

if (SavePictureDialog1->Execute())

  // save the graphic


InputBox Example

This example displays an input dialog box when the user clicks a button on the form. The input dialog box includes a prompt string and a default string. The string the user enters in the dialog box is stored in the InputString variable.

#include <Dialogs.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  AnsiString InputString = InputBox("Input Box", "Prompt", "Default string");

}


InputQuery Example

This example uses a button and a label on the form. When the user clicks the button, the input box displays. If the user chooses OK, the string that appears in the edit box of the dialog box displays as the caption of the label on the form. If the user chooses Cancel, the dialog box closes and the caption of the label remains unchanged.

#include <dialogs.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  AnsiString NewString = "Default String";

  Label1->Caption = NewString;

  if (InputQuery("Input Box", "Prompt", NewString))

    // NewString has been changed by the user, who clicked ok

    Label1->Caption = NewString;

}


AnsiString::Insert Example

AnsiString S = "Honest Lincoln";

S.Insert("Abe ", 8);  // "Honest Abe Lincoln"


IntToHex Example

The following example uses an edit control, a button, and a label on a form. When the button is clicked, the hexadecimal value of each character in the edit control is displayed in the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = "";

  for (int i=0;i<Edit1->Text.Length();i++)

  {

    try

    {

      Label1->Caption = Label1->Caption + IntToHex(Edit1->Text[i+1],4) + " ";

    }

    catch (...)

    {

      MessageBeep(0);

    }

  }

}


IntToStr Example

The following example uses two edit controls, a button, and a label on a form. When the button is clicked, the integers in the edit controls are multiplied together and the result is displayed in the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  try

  {

    Label1->Caption = IntToStr(StrToInt(Edit1->Text) * StrToInt(Edit2->Text));

  }

  catch(...)

  {

    Application->MessageBox("You must specify integer values. Please try again.", "IntToStr Example", IDOK);

  }

}


IsLeapYear Example

The following code defines a function that indicates whether the current year is a leap year.

bool IsThisLeapYear()

{

  Word Yr, Mnth, Day;

  DecodeDate(Date(), Yr, Mnth, Day);

  return IsLeapYear(Yr);

}


LowerCase Example

This example uses an edit control, a label, and a button on a form. When the button is clicked, the label shows the text of the edit control in lower case.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = LowerCase(Edit1->Text);

}


MessageDlgPos Example

This example uses a button on a form. When the user clicks the button, a message box appears with a Yes, No, and Cancel button on it:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  MessageDlgPos("Are you there?",mtConfirmation, TMsgDlgButtons() << mbYesNoCancel, 0, 200, 200);

}


Move Example

This example uses an edit control and a button on a form. When the button is clicked, the bytes representing the text of the edit control are copied into an integer variable. The integer is then displayed in a message box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int i;

  Move((void*)Edit1->Text.c_str(), (void*)&i, sizeof(i));

  Application->MessageBox(IntToStr(i).c_str(), "Move Example", IDOK);

}


ParamStr Example
ParamCount, ParamStr Example

The following example beeps once for each “beep” passed in on the command line. The example terminates the application if  “exit” is passed in on the command line.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i=0;i<=ParamCount();i++)

  {

    if (LowerCase(ParamStr(i)) == "beep")

      Beep(10000,1000);

    if (LowerCase(ParamStr(i)) == "exit")

      Application->Terminate();

  }

}


PasswordDialog Example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (PasswordDialog(Table1->DBSession))

    Table1->Active = true;

}


Polygon, Point Example

This example draws a polygon in the specified shape, and fills it with the color teal:

void __fastcall TForm1::PaintBox1Paint(TObject *Sender)

{

  POINT points[4];

  points[0] = Point(10,10);

  points[1] = Point(30,10);

  points[2] = Point(130,30);

  points[3] = Point(240,120);

  ((TPaintBox *)Sender)->Canvas->Brush->Color = clTeal;

  ((TPaintBox *)Sender)->Canvas->Polygon(points, 3);

}


AnsiString::Pos Example

AnsiString  S = "   123.5";

int p;

 // Convert spaces to zeroes

while ((p = S.Pos(' ')) > 0 )

  S[p] = '0';


RegisterComponents Example

The following code registers several components, one on the System palette page that already exists, and some on a new palette page that C++ Builder creates when the components are installed.

namespace Newcomps

{

  void __fastcall Register()

  {

     TComponentClass sysclasses[1] = {__classid(TSystem1)};

     TComponentClass custclasses[2] = {__classid(TCustom1), __classid(TCustom2)};

    RegisterComponents("System", sysclasses, 0);

    RegisterComponents("NewPage", custclasses, 1);

  }

}


SelectDirectory Example

This example uses a button on a form. When the user clicks the button, a Select Directory dialog box appears. The current directory displayed in the dialog box is C:\MYDIR. The user can select a directory from the directory list, or enter a new directory in the edit box. If the user enters a new directory, a message box asks the user if the directory should be created. If the user chooses Yes, the directory is created. If the user chooses No, the message box goes away without creatubg the directory. The name of the directory the user selects appears as the caption of the label:

#include <FileCtrl.hpp>

const SELDIRHELP = 1000;

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  AnsiString Dir = "C:\Program Files\MyApp";

  if (SelectDirectory(Dir, TSelectDirOpts() << sdAllowCreate << sdPerformCreate << sdPrompt,SELDIRHELP))

    Label1->Caption = Dir;

}


Set8087CW Example

void NumericExample()

{

  Word Saved8087CW = Default8087CW;

  Set8087CW(0x133f);  // Disable all fpu exceptions

  ThirdPartyRoutine();

  Set8087CW(Saved8087CW);

}


SetMemoryManager Example
GetMemoryManager, SetMemoryManager Example

The following example implements a memory manager that counts the number of times the GetMem, FreeMem, and ReallocMem entry points are called. The new memory manager is installed through a call to the SetNewMemMgr routine. The new memory manager routines simply passes on the requests to the previous memory manager after incrementing the appropriate counter.

TMemoryManager* mmNew;

TMemoryManager* mmOld;

int iGetMemCount, iFreeMemCount, iReallocMemCount;

Pointer __fastcall NewGetMem(int iSize);

int __fastcall NewFreeMem(Pointer p);

Pointer __fastcall NewReallocMem(Pointer p, int iSize);

__fastcall TForm1::TForm1(TComponent* Owner): TForm(Owner)

{

  mmNew = new TMemoryManager();

  mmOld = new TMemoryManager();

  mmNew->GetMem = NewGetMem;

  mmNew->FreeMem = NewFreeMem;

  mmNew->ReallocMem = NewReallocMem;

  GetMemoryManager(*mmOld);

  SetMemoryManager(*mmNew);

}

__fastcall TForm1::~TForm1()

{

  delete mmNew;

  delete mmOld;

}

Pointer __fastcall NewGetMem(int iSize)

{

  iGetMemCount++;

  return mmOld->GetMem(iSize);

}

int __fastcall NewFreeMem(Pointer p)

{

  iFreeMemCount++;

  return mmOld->FreeMem(p);

}

Pointer __fastcall NewReallocMem(Pointer p, int iSize)

{

  iReallocMemCount++;

  return mmOld->ReallocMem(p, iSize);

}


ShortCut Example

This line creates a shortcut, Ctrl+O, at run time and assigns it to the Open command on a File menu.

OpenCommand->ShortCut = ShortCut(Word('O'), TShiftState() << ssCtrl);


ShortCutToKey Example

The following code redefines the ShortCut of CloseCommand if the original short cut used a shift state that includes ssCtrl.

Word TheKey;

TShiftState TheShiftState;

ShortCutToKey(CloseCommand->ShortCut, TheKey, TheShiftState);

if (TheShiftState.Contains(ssCtrl))

  CloseCommand->ShortCut = ShortCut(Word('C'), TShiftState() << ssShift);


ShortCutToText Example

This line converts the menu shortcut assigned to the OpenCommand to a string and displays it in an edit box:

Edit1->Text = ShortCutToText(OpenCommand->ShortCut);


ShowMessage Example

This example uses a button on a form. When the user clicks the button, a message dialog box appears with instructions to push the OK button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ShowMessage("Push the OK button");

}


StrCopy, StrCat Example

The following example uses an edit control, a label, and a button on a form. When the button is clicked, the label’s caption and the edit control’s text are combined in a buffer. Then the buffer is displayed in the label’s caption.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szBuffer = new char[Label1->Caption.Length() + Edit1->Text.Length() + 1];

  StrCopy(szBuffer, Label1->Caption.c_str());

  StrCat(szBuffer, Edit1->Text.c_str());

  Label1->Caption = szBuffer;

  Edit1->Clear();

  delete [] szBuffer;

}


StrComp Example

The following example uses two edit controls and a button on a form. When the button is clicked, the text in the edit controls is compared.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szResult = new char[Edit1->Text.Length() + Edit2->Text.Length() + 20];

  int iResult = StrComp(Edit1->Text.c_str(), Edit2->Text.c_str());

  StrCopy(szResult, Edit1->Text.c_str());

  if (iResult < 0)

    StrCat(szResult, " is less than ");

  else if (iResult > 0)

    StrCat(szResult, " is greater than ");

  else

    StrCat(szResult, " is equal to ");

  StrCat(szResult, Edit2->Text.c_str());

  Application->MessageBox(szResult, "StrComp Example", IDOK);

  delete [] szResult;

}


StrECopy Example

The following example uses an edit control, a label, and a button on a form. When the button is clicked, the edit control’s text is appended to a static buffer. Then the buffer is displayed in the label’s caption.

const MAX_LENGTH = 65536;

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  static char szBuffer[MAX_LENGTH];

  static char* pszBuffer = szBuffer;

  if (StrLen(pszBuffer) + StrLen(Edit1->Text.c_str()) < MAX_LENGTH -1)

    pszBuffer = StrECopy(pszBuffer, Edit1->Text.c_str());

  else

    Application->MessageBox("Can't fit new string in allocated memory space.", "StrECopy Example", IDOK);

  Label1->Caption = szBuffer;

  Edit1->Clear();

}


StrEnd Example

The following example uses an edit control, a label, and a button on a form. When the button is clicked, the edit control’s text is copied into a buffer. Then the buffer is displayed backwards in the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char *pszEditText = new char[Edit1->Text.Length()+1];

  char *psz;

  StrCopy(pszEditText, Edit1->Text.c_str());

  psz = StrEnd(pszEditText);

  Label1->Caption = "";

  while (psz >= &pszEditText[0])

  {

    psz--;

    Label1->Caption = Label1->Caption + *psz;

  }

  delete [] pszEditText;

}


StrlComp Example

The following example uses two edit controls and a button on a form. When the button is clicked, the text in the edit controls are compared case-insensitively.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szResult = new char[Edit1->Text.Length() + Edit2->Text.Length() + 20];

  int iResult = StrIComp(Edit1->Text.c_str(), Edit2->Text.c_str());

  StrCopy(szResult, Edit1->Text.c_str());

  if (iResult < 0)

    StrCat(szResult, " is less than ");

  else if (iResult > 0)

    StrCat(szResult, " is greater than ");

  else

    StrCat(szResult, " is equal to ");

  StrCat(szResult, Edit2->Text.c_str());

  Application->MessageBox(szResult, "StrIComp Example", IDOK);

  delete [] szResult;

}


StrLen, StrLCat Example

The following example uses an edit control and a button on a form. When the button is clicked, the edit control’s text is split in halves that are copied into separate buffers. Then the contents of the buffers are displayed in a message box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szFirstHalf = new char[StrLen(Edit1->Text.c_str())/2+2];

  char* szSecondHalf = new char[StrLen(Edit1->Text.c_str())/2+2];

  char* pszSecondHalf = &Edit1->Text[StrLen(Edit1->Text.c_str())/2+1];

  *szFirstHalf = 0;

  *szSecondHalf = 0;

  StrLCat(szFirstHalf, Edit1->Text.c_str(), StrLen(Edit1->Text.c_str())/2);

  StrCat(szSecondHalf, pszSecondHalf);

  Application->MessageBox(szFirstHalf, "First Half", MB_OK);

  Application->MessageBox(szSecondHalf, "Second Half", MB_OK);

  delete [] szFirstHalf;

  delete [] szSecondHalf;

}


StrLComp Example

The following example uses two edit controls and a button on a form. When the button is clicked, the first X bytes of the edit controls are compared, where X is the number of characters in the shorter string. To do a case-insensitive compare, use StrLIComp instead of StrLComp.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szResult = new char[Edit1->Text.Length() + Edit2->Text.Length() + 65];

  int len = min(Edit1->Text.Length(), Edit2->Text.Length());

  int iResult = StrLComp(Edit1->Text.c_str(), Edit2->Text.c_str(), len);

  StrCopy(szResult, "The first ");

  StrCat(szResult, IntToStr(len).c_str());

  StrCat(szResult, " bytes of ")

  StrCat(szResult, Edit1->Text.c_str());

  if (iResult < 0)

    StrCat(szResult, " are less than the first ");

  else if (iResult > 0)

    StrCat(szResult, " are greater than the first ");

  else

    StrCat(szResult, " are equal to the first ");

  StrCat(szResult, IntToStr(len).c_str());

  StrCat(szResult, " bytes of ");

  StrCat(szResult, Edit2->Text.c_str());

  ShowMessage(szResult);

  delete [] szResult;

};


StrLCopy Example

The following example uses an edit control and a button on a form. When the button is clicked, the first X bytes of the edit control are copied into a buffer, where X is a predefined number.

const MAX_BUFFER = 10;

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char szBuffer[MAX_BUFFER+1];

  StrLCopy(szBuffer, Edit1->Text.c_str(), MAX_BUFFER);

  Application->MessageBox(szBuffer, "StrLCopy Example", MB_OK);

}


StrLIComp Example

The following example uses two edit controls and a button on a form. When the button is clicked, the first X bytes of the edit controls are compared, where X is the number of characters in the shorter string. To do a case-sensitive compare, use StrLComp instead of StrLIComp.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szResult = new char[Edit1->Text.Length() + Edit2->Text.Length() + 65];

  int len = min(Edit1->Text.Length(), Edit2->Text.Length());

  int iResult = StrLIComp(Edit1->Text.c_str(), Edit2->Text.c_str(), len);

  StrCopy(szResult, "The first ");

  StrCat(szResult, IntToStr(len).c_str());

  StrCat(szResult, " bytes of ")

  StrCat(szResult, Edit1->Text.c_str());

  if (iResult < 0)

    StrCat(szResult, " are less than the first ");

  else if (iResult > 0)

    StrCat(szResult, " are greater than the first ");

  else

    StrCat(szResult, " are equal to the first ");

  StrCat(szResult, IntToStr(len).c_str());

  StrCat(szResult, " bytes of ");

  StrCat(szResult, Edit2->Text.c_str());

  ShowMessage(szResult);

  delete [] szResult;

};


StrLower Example

The following example uses an edit box, a label, and a button on a form. When the button is clicked, the text in the edit control is displayed in lower case in the label’s caption.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = StrLower(Edit1->Text.c_str());

}


StrMove Example

This example shows two functions that do the same thing as StrNew and StrDispose.

char * AHeapaString(char *S)

{

// Allocate string on heap

  if ((S != NULL) && (S[0] != '\0'))

  {

    int L = StrLen(S) + 1;

    char *p = (char *)malloc(L);

    return StrMove(p, S, L);

  }

  return NULL;

}

void DisposeDaString(char *S)

{

// Dispose string on heap

  if (S != NULL)

    free(S);

}


StrNew Example
StrNew, StrDispose Example

This example uses an edit control and a button on a form. When the button is clicked, memory is allocated for a copy of the text in the edit control, the text is displayed in a message box, and then the memory is deallocated.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  // Allocate memory.

  char* psz = StrNew(Edit1->Text.c_str());

  Application->MessageBox(psz, "StrNew, StrDispose Example", MB_OK);

  // Deallocate memory.

  StrDispose(psz);

}


StrPCopy Example

The following example uses an edit control, a label, and a button on a form. When the button is clicked, the label’s caption and the edit control’s text are combined in a buffer. Then the buffer is displayed in the label’s caption.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char* szBuffer = new char[Label1->Caption.Length() + Edit1->Text.Length() + 1];

  StrPCopy(szBuffer, Label1->Caption);

  StrCat(szBuffer, Edit1->Text.c_str());

  Label1->Caption = szBuffer;

  Edit1->Clear();

  delete [] szBuffer;

}


StrPos Example

The following example uses two edit controls and a button on a form. When the button is clicked, the text in the first edit control is searched for the text in the second edit control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (StrPos(Edit1->Text.c_str(), Edit2->Text.c_str()))

    Application->MessageBox("Substring found.", "Substring Found", MB_OK);

  else

    Application->MessageBox("Substring not found.", "Substring Not Found", MB_OK);

}


StrRScan Example

The following example uses an Open dialog box and a button on a form. When the button is clicked, the user is prompted for a filename. Then the filename, minus its path, is displayed in a message box.

Note:	This technique will not work with multi-byte character sets (MBCS).

char* __fastcall GetFileName(char* pszFilePath)

{

  char* pszFileName = StrRScan(pszFilePath, '\\');

  if (!pszFileName)

    pszFileName = pszFilePath;

  else

    pszFileName++;

  return pszFileName;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (OpenDialog1->Execute())

  Application->MessageBox(GetFileName(OpenDialog1->FileName.c_str()),

"File Name", MB_OK);

}


StrScan Example

The following example uses an edit control and a button on a form. When the button is clicked, the text in the edit control is searched for a wildcard (asterisk character).

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (StrScan(Edit1->Text.c_str(), '*'))

    ShowMessage("Wildcard found.");

  else

    ShowMessage("Wildcard not found.");

}


StrToDate Example

This example uses an edit box and a button on a form. When the user enters a date in the edit box in the MM/DD/YY format, the string entered is converted to a TDateTime value. This value is used to indicate the day of the week the number represents.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char days[7][10] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" };

  TDateTime dtDate = StrToDate(Edit1->Text);

  ShowMessage(Edit1->Text + AnsiString(" is a ") + days[dtDate.DayOfWeek()]);

}


StrToDateTime Example

This example sets the value of a date-time field based on the value typed by the user into an edit control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TDateTime dtValue = StrToDateTime(Edit1->Text);

  Table1->FieldByName("TimeStamp")->AsDateTime = dtValue;

}


StrToInt Example

This example uses two edit boxes and a button on a form. When the user clicks the button, the code converts the values in the edit boxes to numbers, adds them, and displays a message indicating the sum:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int i1, i2;

  i1 = StrToInt(Edit1->Text);

  i2 = StrToInt(Edit2->Text);

  ShowMessage(IntToStr(i1 + i2));

}


StrToTime Example

This example uses an edit box, and a button on a form. When the user enters a time in the edit box in the HH:MM:SS format, the string entered is converted to a TDateTime value. A message then appears that says “Good Morning” or “Good Afternoon”, depending on whether the time entered was in the morning or afternoon.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TDateTime dtTime = StrToTime(Edit1->Text);

  if (dtTime < (TDateTime) 0.50 )

    ShowMessage("Good Morning");

  else

    ShowMessage("Good Afternoon");

}


StrUpper Example

The following example uses an edit box, a label, and a button on a form. When the button is clicked, the text in the edit control is displayed in upper case in the label’s caption.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = StrUpper(Edit1->Text.c_str());

}


SystemTimeToDateTime Example

The following code retrieves the current date and time using the Windows GetLocalTime API call, and converts this value to a TDateTime value.

TDateTime __fastcall GetCurrentDateTime()

{

  SYSTEMTIME SystemTime;

  GetLocalTime(&SystemTime);

  return SystemTimeToDateTime(SystemTime);

}


TextToShortCut Example

This example uses a main menu that contains an Open command, an edit box, and a button. Delphi automatically names the menu item for the Open command Open1. When the user enters the desired shortcut text in the edit box and clicks the button, a shortcut is created and the shortcut text appears next to the Open menu item.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Open1->ShortCut = TextToShortCut(Edit1->Text);

}


Time Example
Time, TimeToStr Example

This example uses a label and a button on a form. When the user clicks the button, the current time displays in the caption of the label:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->Caption = AnsiString("The time is  ") + TimeToStr(Time());

}


UpCase Example

The following code uppercases every other character in the text of an edit control when the user clicks the button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  // Get string from TEdit control

  AnsiString s = Edit1->Text;

  for (int i = 0; i < s.Length(); i += 2)

  {

    s[i] = UpCase(s[i]);

    Edit1->Text = s;

  }

}


UpperCase Example

This example uses a list box and a button on a form. Use the Items property editor in the Object Inspector to enter a list of strings in the list box. When the application runs and the button is clicked, the strings in the list box become uppercase.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for (int I = 0; I < ListBox1->Items->Count; I++)

    ListBox1->Items->Strings[I] = UpperCase(ListBox1->Items->Strings[I]);

}


VarArrayCreate, VarArrayOf Example

The following example creates a one-dimensional variant array with five elements. Each of the elements are of type Variant, and can therefore contain values of varying types, as is illustrated by the example. Notice in particular how the value of the last element of the array is itself a variant array.

Variant A = VarArrayCreate(OPENARRAY(int, (0,4)), varVariant);

A[0] = 1;

A[1] = 1234.5678;

A[2] = "Hello world";

A[3] = true;

A[4] = VarArrayOf(ARRAYOFCONST(((int)1, (int)10, (int)100)));


VarArrayLock Example

typedef int TArrayData[10][3];

Variant A = VarArrayCreate(OPENARRAY(int, (0, 2, 0, 9)), varInteger);

TArrayData *P = (TArrayData *)VarArrayLock(A);

try

{

  for (int i = 0; i < 10; i++)

    for (int j = 0; j < 3; j++)

      (*P)[i][j] = j * 10 + i;

}

catch (...)

{

  VarArrayUnlock(A);

  throw;

}

VarArrayUnlock(A);


Application Example

This code displays the name of your project in an edit box:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Edit1->Text = Application->Title;

}


Currency and date/time formatting Example

This example uses a label and a button on a form. When the user clicks the button, the current date displays in the caption of the label. Because some of the date variables are assigned new values, the format of the date in the label changes. For example, if the date is 9/15/94, the date displays as 15-09-1994.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  DateOrder = doDMY;

  DateSeparator = '-';

  DateFullYear = true;

  DateLeadZero = true;

  Label1->Caption = DateToStr(Date());

}


ErrorProc Example

extern void __fastcall MyErrorHandler(int ErrorCode, void * ErrorAddr);

ErrorProc = MyErrorHandler;


Screen Example

The following code sets the width of a form called Form1 to half the width of the screen:

Form1->Width = Screen->Width/2;


TDragState Example

This code is a OnDragOver event handler that won't allow a label control to be dropped on a panel control and stops the dragging of the label as soon as the user drags the label onto the panel:

void __fastcall TForm1::Panel1DragOver(TObject *Sender, TObject *Source, int X, int Y, TDragState State, bool &Accept)

{

  Accept = false;

  if ((Source->ClassNameIs("TLabel") && (State == dsDragEnter))

    ((TLabel *)Source)->EndDrag(false);

}

The Source parameter is the label being dragged, the Sender parameter is the panel control, and the State parameter is the drag state.


TVarData Example

This example shows how to use the  TVarData type in typecasts of Variant variables to access the internals of a variable.

Variant V;

if (((TVarData)V).VType == varEmpty)

{

  VarClear(V);

  ((TVarData)V).VType = varInteger;

  ((TVarData)V).VInteger = 1234567;

}


Unassigned Example

In the code fragment shown below, the statement that assigns Unassigned to the MSWord variable causes the OLE Automation Object that was created to interface with Word to be released.

Variant MSWord = CreateOleObject("Word.Basic");

...

MSWord = Unassigned;


Global Routines

The VCL and Object Pascal RTL include many global routines are useful in application development.  The routines found in the source files of the VCL are tailored to work with specific objects.  The Object Pascal RTL includes general purpose routines affecting the flow of control or performing commonly needed programming tasks.  These include

•	Mathematical and statistical routines

•	Strings, type conversion, and formatting

•	File utilities

•	User interface utilities

•	Database utilities

•	Programming utilities

•	Component writer utilities

•	Miscellaneous


Mathematical and statistical routines

The mathematical and statistical routines can be divided into the following categories

•	Arithmetic routines

•	Business and finance routines

•	Measurement conversion routines

•	Random number routines

•	Statistical routines

•	Trigonometry routines


Strings, type conversion, and formatting

The routines for strings, type conversion, and formatting can be divided into the following categories:

•	Date/Time routines

•	Floating-point conversion routines

•	MBCS utilities

•	Numeric formatting routines

•	String formatting routines

•	String handling routines

•	String handling routines (null-terminated)

•	Type conversion routines

•	Wide character routines


File utilities

The file utilities can be divided into the following categories

•	File name utilities

•	File management routines


User interface utilities
 AUser interface utilities

The user interface utilities can be divided into the following categories

•	Clipboard routines

•	Cursor management routines

•	Drag and drop routines

•	Dialog and Message routines

•	Graphics utilities

•	Windows controls utilities

•	Help Hint routines

•	Menu support routines

•	Mouse handling utilities


Programming utilities

The programming utilities can be divided into the following categories

•	Command line utilities

•	Exception handling routines

•	Memory manager routines


Component writer utilities

The component writer utilities can be divided into the following categories

•	Class handling routines

•	Component registration routines

•	Design tool registration routines

•	Package support routines

•	Streaming utilities


Miscellaneous routines

The remaining routines can be divided into the following categories

•	Backward compatibility routines

•	COM utilities

•	HTTP utilities

•	Miscellaneous routines

•	Variant support routines


AdjustLineBreaks

See also

Standardizes line break characters to LF/CF.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall AdjustLineBreaks(const System::AnsiString S);

Description

AdjustLineBreaks adjusts all line breaks in the given AnsiString S to be true CR/LF sequences. The function changes any CR characters not followed by a LF and any LF characters not preceded by a CR into CR/LF pairs. It also converts LF/CR pairs to CR/LF pairs. The LF/CR pair is common in Unix text files.


AllocMem

See also

Allocates a memory block and initializes each byte to zero.

Unit

SysUtils

Category

memory management routines

extern PACKAGE void * __fastcall AllocMem(Cardinal Size);

Description

AllocMem allocates a block of the given size on the heap. Each byte in the allocated buffer is set to zero. To dispose the buffer, use SysFreeMem.


AnsiCompareFileName

See also

Compares file names based on the current locale.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE int __fastcall AnsiCompareFileName(const System::AnsiString S1, const System::AnsiString S2);

Description

AnsiCompareFileName compares S1 to S2, without case sensitivity. The compare operation is controlled by the currently installed language driver. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2	= 0
AnsiCompareFileName supports DOS file name comparison idiosyncracies in Asian locales (Zenkaku).  When working with locales that do not use a multi byte character system (MBCS), AnsiCompareFileName is identical to AnsiCompareText.  For general purpose file name comparisions, use this function instead of AnsiCompareText.


AnsiCompareStr

See also

Compares AnsiStrings based on the current Windows locale and is case sensitive.

Unit

SysUtils

Category

string handling routines

extern PACKAGE int __fastcall AnsiCompareStr(const System::AnsiString S1, const System::AnsiString S2);

Description

AnsiCompareStr compares S1 to S2, with case sensitivity. The compare operation is controlled by the current Windows locale. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2	= 0
Note:	Most Windows locales consider lowercase characters to be less than the corresponding uppercase characters.  This is in contrast to ASCII order, in which lowercase characters are greater than uppercase characters.  Thus,

AnsiCompareStr('a','A')

returns a value less than zero, while

CompareStr('a','A')

returns a value greater than zero.


AnsiCompareText

See also

Compares AnsiStrings based on the current Windows locale and is not case sensitive.

Unit

SysUtils

Category

string handling routines

extern PACKAGE int __fastcall AnsiCompareText(const System::AnsiString S1, const System::AnsiString S2);

Description

AnsiCompareText compares S1 to S2, without case sensitivity. The compare operation is controlled by the current Windows locale. AnsiCompareText returns a value less than 0 if S1 < S2, a value greater than 0 if S1 > S2, and returns 0 if S1 = S2.


AnsiExtractQuotedStr

See also

Converts a quoted string into an unquoted AnsiString.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall AnsiExtractQuotedStr(char * &Src, char Quote);

Description

AnsiExtractQuotedStr removes the quote characters from the beginning and end of a quoted string, and reduces pairs of quote characters within the string to a single quote character. The Quote parameter defines what character to use as a quote character. If the first character in Src is not the value of the Quote parameter, AnsiExtractQuotedStr returns an empty AnsiString.

The function copies characters from Src to the result AnsiString until the second solitary quote character or the first null character in Src. The Src parameter is updated to point to the first character following the quoted string.  If Src does not contain a matching end quote character, the Src parameter is updated to point to the terminating null character.

Note:	This function supports multi-byte character sets (MBCS).


AnsiLastChar

See also

Returns a pointer to the last character in a string.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE char * __fastcall AnsiLastChar(const System::AnsiString S);

Description

Call AnsiLastChar to obtain locate the last character in a string. This function supports multi-byte character sets (MBCS).


AnsiLowerCase

See also

Returns an AnsiString that is a copy of the given AnsiString converted to lower case.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall AnsiLowerCase(const System::AnsiString S);

Description

AnsiLowerCase returns an AnsiString that is copy of the given AnsiString converted to lower case. The conversion uses the current Windows locale. This function supports multi-byte character sets (MBCS).


AnsiLowerCaseFileName

See also

Converts a file name to lower case.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE System::AnsiString __fastcall AnsiLowerCaseFileName(const System::AnsiString S);

Description

AnsiLowerCaseFileName returns an AnsiString that is a copy of S converted to lower case. The conversion uses the currently installed language driver.

AnsiLowerCaseFileName supports lowercase conversion idiosyncracies of DOS file names in Asian locales (Zenkaku).  In locales that do not use multi byte character systems (MBCS), AnsiLowerCaseFileName is identical to AnsiLowerCase.


AnsiPos

See also

Locates the position of a sub-string within an AnsiString.

Unit

SysUtils

Category

string handling routines

extern PACKAGE int __fastcall AnsiPos(const System::AnsiString Substr, const System::AnsiString S);

Description

Call AnsiPos to obtain the byte offset of the Substr parameter, as it appears in the AnsiString S. For example, if Substr is the AnsiString 'AB', and S is the AnsiString 'ABCDE', AnsiPos returns 1. If Substr does not appear in the AnsiString S, AnsiPos returns 0.

Note:	This function supports multi-byte character sets (MBCS).


AnsiQuotedStr

See also

Returns the quoted version of an AnsiString.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall AnsiQuotedStr(const System::AnsiString S, char Quote);

Description

Use AnsiQuotedStr to convert the AnsiString S to a quoted AnsiString, using the provided Quote character.  A Quote character is inserted at the beginning and end of S, and each Quote character in the AnsiString is doubled.

Note:	This function supports multi-byte character sets (MBCS).


AnsiStrComp

See also

Compares null-terminated character strings case sensitively.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall AnsiStrComp(char * S1, char * S2);

Description

AnsiStrComp compares S1 to S2, with case sensitivity. The compare operation is controlled by the current Windows locale. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2	= 0
Note:	Most Windows locales consider lowercase characters to be less than the corresponding uppercase characters.  This is in contrast to ASCII order, in which lowercase characters are greater than uppercase characters.

Note:	This function supports multi-byte character sets (MBCS).


AnsiStrIComp

See also

Compares null terminated character strings case insensitively.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall AnsiStrIComp(char * S1, char * S2);

Description

AnsiStrIComp compares S1 to S2, without case sensitivity. The compare operation is controlled by the current Windows locale. The return value is the same as for CompareStr.

Note:	This function supports multi-byte character sets (MBCS).


AnsiStrLastChar

See also

Returns a pointer to the last character in a null-terminated sequence of characters.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE char * __fastcall AnsiStrLastChar(char * P);

Description

Call AnsiStrLastChar to obtain a pointer to the last full character in a null-terminated sequence. When working with multi-byte character sets (MBCS), the last character will not be the same as the last char if the last two bytes (chars) represent a single double byte character.


AnsiStrLComp

See also

Compares the first MaxLen bytes of two character sequences, case-sensitively.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall AnsiStrLComp(char * S1, char * S2, Cardinal MaxLen);

Description

AnsiStrLComp compares S1 to S2, with case sensitivity. If S1 or S2 is longer than MaxLen bytes, AnsiStrLComp only compares the first MaxLen bytes. The compare operation is controlled by the current Windows locale. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2 (up to MaxLen characters)	= 0
Note:	This function supports multi-byte character sets (MBCS).

Note:	AnsiStrLComp can continue the comparison beyond a null terminating character if S1 and S2 are equal up to a null character and the null character occurs before MaxLen bytes.

Note:	Most Windows locales consider lowercase characters to be less than the corresponding uppercase characters.  This is in contrast to ASCII order, in which lowercase characters are greater than uppercase characters.


AnsiStrLIComp

See also

Compares two strings, case-insensitively, up to the first MaxLen bytes.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall AnsiStrLIComp(char * S1, char * S2, Cardinal MaxLen);

Description

AnsiStrLIComp compares S1 to S2, without case sensitivity. If S1 or S2 is longer than MaxLen characters, AnsiStrLIComp only compares up to the first MaxLen characters. The compare operation is controlled by the current Windows locale. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2 (up to MaxLen characters)	= 0
Note:	This function supports multi-byte character sets (MBCS).

Note:	AnsiStrLIComp can continue the comparison beyond a null terminating character if S1 and S2 are equal up to a null character and the null character occurs before MaxLen bytes.


AnsiStrLower

See also

Converts all characters in a null-terminated character sequence to lower case.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall AnsiStrLower(char * Str);

Description

AnsiStrLower returns a null-terminated character sequence where all characters are lower case. The conversion uses the current Windows locale.

Note:	This function supports multi-byte character sets (MBCS).


AnsiStrPos

See also

Returns a pointer to the first occurance of STR2 in STR1.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall AnsiStrPos(char * Str, char * SubStr);

Description

Call AnsiStrPos to locate the first occurrence of Str2 in Str1. If Str2 does not occur in Str1, AnsiStrPos returns NULL.

Unlike the StrPos function, AnsiStrPos works with multi-byte characters sets (MBCS).


AnsiStrRScan

See also

Returns a pointer to the last occurance of Chr in STR.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall AnsiStrRScan(char * Str, char Chr);

Description

Call AnsiStrRScan to obtain a pointer to the last occurrence of Chr in Str. If Chr does not occur in Str, AnsiStrRScan returns NULL. The null terminator is considered to be part of the string.

Unlike the StrRScan function, AnsiStrRScan works with multi-byte character systems (MBCS).


AnsiStrScan

See also

Returns a pointer to first occurrence of a character in a string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall AnsiStrScan(char * Str, char Chr);

Description

Call AnsiStrScan to obtain a pointer to the first occurrence of Chr in Str. If Chr does not occur in Str, AnsiStrScan returns NULL. The null terminator is considered to be part of the string.

Unlike the StrScan function, AnsiStrScan works with multi-byte character systems (MBCS).


AnsiStrUpper

See also

Ronverts all characters in a null-terminated character sequence to upper case.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall AnsiStrUpper(char * Str);

Description

AnsiStrUpper returns a null-terminated character sequence where all characters are upper case. The conversion uses the current Windows locale.

Note:	This function supports multi-byte character sets (MBCS).


AnsiToNative

See also

Converts an AnsiString from the ANSI character set to the character set associated with a given locale.

Unit

DBTables

Category

BDE support routines

extern PACKAGE char * __fastcall AnsiToNative(void * Locale, const System::AnsiString AnsiStr, char * NativeStr, int MaxLen);

Description

Call AnsiToNative to convert an AnsiString represented in the ANSI character set (used internally by the VCL) to the character set associated with the locale specified by the Locale parameter. The resulting string is copied into the buffer pointed to by the NativeStr parameter. Use the MaxLen parameter to specify the size of this buffer. If the buffer is too small to contain all characters in the converted version of AnsiStr, the returned value is truncated. AnsiToNative returns a pointer to NativeStr.

Use AnsiToNative to convert strings typed by the user into the character set used by a database table.


AnsiToNativeBuf

See also

Converts a string from the ANSI character set to the character set associated with a given locale.

Unit

DBTables

Category

BDE support routines

extern PACKAGE void __fastcall AnsiToNativeBuf(void * Locale, char * Source, char * Dest, int Len);

Description

Call AnsiToNativeBuf to convert a character sequence in the ANSI character set (used internally by the VCL) to the character set associated with the locale specified by the Locale parameter. The resulting string is copied into the buffer pointed to by the Dest parameter. Use the Len parameter to specify the size of this buffer.

Use AnsiToNativeBuf to convert strings typed by the user into the character set used by a database table.


AnsiUpperCase

See also

Converts an AnsiString to upper case.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall AnsiUpperCase(const System::AnsiString S);

Description

AnsiUpperCase returns an AnsiString that is a  copy of the AnsiString, S, converted to upper case. The conversion uses the current Windows locale.

Note:	This function supports multi-byte character sets (MBCS).


AnsiUpperCaseFileName

See also

Converts a file name to upper case.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE System::AnsiString __fastcall AnsiUpperCaseFileName(const System::AnsiString S);

Description

AnsiLowerCaseFileName returns an AnsiString that is a copy of S converted to upper case. The conversion uses the currently installed language driver.

AnsiUpperCaseFileName supports uppercase conversion idiosyncracies of DOS file names in Asian locales (Zenkaku).  In locales that do not use multi byte character systems (MBCS), AnsiUpperCaseFileName is identical to AnsiUpperCase.


AppendStr

Appends a dynamically allocated AnsiString to an existing AnsiString.

Unit

SysUtils

Category

string handling routines

extern PACKAGE void __fastcall AppendStr(System::AnsiString &Dest, const System::AnsiString S);

Description

AppendStr appends S to the end of Dest.


ArcCos

Calculates the inverse cosine of the given number.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall ArcCos(Extended X);

Description

ArcCos returns the inverse cosine of X. X must be between -1 and 1. The return value will be in the range [0..Pi], in radians.


ArcCosh

See also

Calculates the inverse hyperbolic cosine of the given number.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall ArcCosh(Extended X);

Description

ArcCosh returns the inverse hyperbolic cosine of X.  The value of X must be greater than or equal to 1.


ArcSin

Calculates the inverse sine of the given number.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall ArcSin(Extended X);

Description

ArcSin returns the inverse sine of X. X must be between -1 and 1. The return value will be in the range [-Pi/2..Pi/2], in radians.


ArcSinh

See also

Calculates the inverse hyperbolic sine of the given number.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall ArcSinh(Extended X);

Description

ArcSinh returns the inverse hyperbolic sine of X.


ArcTanh

See also

Calculates the inverse hyperbolic tangent of the given number.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall ArcTanh(Extended X);

Description

ArcTanh returns the inverse hyperbolic tangent of X.  The value of X must be between -1 and 1 (inclusive).


ArcTan2

Calculates the arctangent angle and quadrant of the given number.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall ArcTan2(Extended Y, Extended X);

Description

ArcTan2 calculates ArcTan(Y/X), and returns an angle in the correct quadrant.  The values of X and Y must be between -264 and 264.  In addition, the value of X can’t be 0.  The return value will fall in the range from -Pi to Pi radians.


Beep

Generates a standard beep using the computer speaker.

Unit

SysUtils

Category

miscellaneous routines

extern PACKAGE void __fastcall Beep(void);

Description

Beep calls the Windows API MessageBeep.


Bounds

See also

Returns the TRect for a rectangle of a given position, width, and height.

Unit

Classes

Category

type conversion routines

extern PACKAGE Windows::TRect __fastcall Bounds(int ALeft, int ATop, int AWidth, int AHeight);

Description

Call Bounds to obtain a TRect for a rectangle with upper left corner at the point (ALeft, ATop) with width AWidth and height AHeight.


ByteToCharIndex

See also

Returns the position of the character that contains a specified byte in an AnsiString.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE int __fastcall ByteToCharIndex(const System::AnsiString S, int Index);

Description

Call ByteToCharIndex to determine which character contains a particular byte in an AnsiString, where 1 specifies the first byte, 2 specifies the second byte, and so on. If the Index parameter specifies a byte that is not in the AnsiString (Index < 0 or Index > Length(S)), ByteToCharIndex returns 0.

If the system does not use a multi-byte character system (MBCS), ByteToCharIndex simply returns the value of Index, because there is a 1:1 correspondance between bytes and characters. Othersize, ByteToCharIndex returns the position of the character, where 1 specifies the first character, 2 specifies the second character, and so on.

For example, if an AnsiString contains two characters, a single-byte character followed by a double byte character, then ByteToCharIndex returns 1 when Index is 1, it returns 2 when Index is 2 or 3, and it returns 0 for any other value of Index.


ByteToCharLen

See also

Returns the number of characters fully contained in the first MaxLen bytes of an AnsiString.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE int __fastcall ByteToCharLen(const System::AnsiString S, int MaxLen);

Description

Call ByteToCharLen to determine the number of characters represented by a portion of an AnsiString. ByteToCharLen counts characters until it reaches MaxLen bytes or the end of the AnsiString, whichever comes first.

When working with multi-byte character systems (MBCS), the value returned by ByteToCharLen may be less than MaxLen or the length of the AnsiString.

Note:	ByteToCharLen will count a partial character if it appears as the last of the first MaxLen bytes.


ByteType

See also

Indicates whether a byte in an AnsiString is a single byte character, the first byte of a double byte character, or the second byte of a double byte character.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE TMbcsByteType __fastcall ByteType(const System::AnsiString S, int Index);

Description

Call ByteType to determine the type of the byte specified by the Index parameter, where 0 specifies the first byte in the AnsiString S, 1 specifies the second byte, and so on.

If the system is not using a multi-byte character system (MBCS), ByteType always returns mbSingleByte. Otherwise, ByteType returns mbSingleByte if the indicated byte represents a complete character in S, mbLeadByte if it represents the first byte of a double byte character, and mbTrailByte if it represents the second byte of a double byte character.

Note:	No checking is done to ensure that Index is less than the length of S. It is the caller's responsibility to ensure that Index is not out of bounds.


CancelDrag

Cancels a drag-and-drop operation that is in progress.

Unit

Controls

Category

drag and drop routines

extern PACKAGE void __fastcall CancelDrag(void);

Description

Call CancelDrag to terminate the current drag-and-drop operation without dropping the dragged object.


Ceil

Rounds variables up toward positive inifinity.

Unit

Math

Category

arithmetic routines

extern PACKAGE int __fastcall Ceil(Extended X);

Description

Call Ceil to obtain the lowest integer greater than or equal to X. The absolute value of X must be less than MaxInt.  For example:

Ceil(-2.8) = -2

Ceil(2.8) = 3

Ceil(-1.0) = -1


ChangeFileExt

See also 	Example

Changes the file extension.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ChangeFileExt(const System::AnsiString FileName, const System::AnsiString Extension);

Description

ChangeFileExt takes the file name passed in FileName and changes the extension of the file name to the extension passed in Extension.  ChangeFileExt does not rename the actual file, it just creates a new file name string.

Note:	This function works with multi-byte character sets (MBCS).


CharsetToIdent

See also

Obtains the name of a character set.

Unit

Graphics

Category

graphics utilities

extern PACKAGE bool __fastcall CharsetToIdent(int Charset, System::AnsiString &Ident);

Description

Call CharsetToIdent to obtain the symbolic name for the character set of a font. CharsetToIdent returns true if the Ident parameter is successfully given an identifying name for the character set.

Note:	The return value of CharsetToIdent does not indicate whether the Charset parameter is valid for a given font. Many fonts support only a limited number of character sets. Some fonts may support less common character sets that can't be mapped to identifiers by CharsetToIdent.


CharToByteIndex

See also

Returns the 1-based index of the first byte of a specified character in an AnsiString.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE int __fastcall CharToByteIndex(const System::AnsiString S, int Index);

Description

Call CharToByteIndex to obtain the byte offset for the character at a specified position in the AnsiString S, where 1 specifies the first character, 2 specifies the second character, and so on. CharToByteIndex returns zero if Index is out of range (Index <= 0 or S contains fewer than Index characters). If the character indicated by the Index parameter is a double-byte character, CharToByteIndex returns the offset of the first byte.

If the system is not using a multi-byte character system (MBCS), CharToByteIndex returns the value of Index, because there is a 1:1 correspondance between bytes and characters.


CharToByteLen

See also

Returns the length, in bytes, of the first MaxLen characters of an AnsiString.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE int __fastcall CharToByteLen(const System::AnsiString S, int MaxLen);

Description

Call CharToByteLen to convert the length of an AnsiString in characters to the corresponding length in bytes. CharToByteLen returns the number of bytes required by the first MaxLen characters of S. If S contains fewer than MaxLen characters, CharToByteLen returns the byte length of the AnsiString S.

If the system is not using a multi-byte character system (MBCS), CharToByteLen returns the length of S or MaxLen, whichever is smaller.


Check procedure
Check

See also

Determines whether a value returned from the Borland Database Engine (BDE) represents an error condition.

Unit

DBTables

Category

BDE support routines

extern PACKAGE void __fastcall Check(Word Status);

Description

Pass the return code from a direct BDE API call as the Status parameter when calling Check. Check determines whether Status indicates an error condition, and if so, calls DbiError to throw an exception.


CheckToolMenuDropdown procedure
CheckToolMenuDropdown

See also

Displays a tool button’s dropdown menu.

Unit

ComCtrls

Category

Windows controls utilities

extern PACKAGE void __fastcall CheckToolMenuDropdown(TToolButton* ToolButton);

Description

Call CheckToolMenuDropdown to programatically display the dropdown menu for a tool button of style tbsDropDown.  If the tool button has no associated dropdown menu, CheckToolMenuDropDown does nothing.


ClassIDToProgID

See also

Returns the programmatic ID for a specified class given its class ID (CLSID).

Unit

ComObj

Category

COM utilities

extern PACKAGE System::AnsiString __fastcall ClassIDToProgID(const GUID &ClassID);

Description

ClassIDToProgID retrieves the programmatic ID for a given CLSID. The ClassID parameter specifies the CLSID for which the programmatic ID is requested.

If ClassIDToProgID succeeds ClassIDToProgID returns an AnsiString to the requested ProgID. If ClassIDToProgID fails an EOleSysError exception is thrown with an error code indicating the cause of the error. The error code possibilites are as follows:

Error code	Meaning
REGDB_E_CLASSNOTREG	Class not registered in the registry.
REGDB_E_READREGDB	Error reading registry.


Clipboard

See also

Returns an instance of TClipboard.

Unit

clipbrd

Category

clipboard routines

extern PACKAGE TClipboard* __fastcall Clipboard(void);

Description

C++Builder maintains a single instance of TClipboard for use whenever the application needs to directly access the clipboard object. If the application has never used the Windows clipboard, calling Clipboard creates a new instance of TClipboard. If the clipboard has already been used, Clipboard returns the previously created TClipboard object.

To use Clipboard and the TClipboard object, include Clipbrd.hpp in the source module.


CollectionsEqual

See also

Compares the contents of two collections.

Unit

Classes

Category

miscellaneous routines

extern PACKAGE bool __fastcall CollectionsEqual(TCollection* C1, TCollection* C2);

Description

Call CollectionsEqual to determine whether two collections contain identical information. CollectionsEqual returns true if all the items in each collection have the same settings, and the items appear in the same order. CollectionsEqual returns false if the collections differ in number or order of items, or if any of the items in the collections differ.


ColorToIdent

See also

Provides the symbolic name of a TColor value.

Unit

Graphics

Category

graphics utilities

extern PACKAGE bool __fastcall ColorToIdent(int Color, System::AnsiString &Ident);

Description

Call ColorToIdent to obtain the name of the symbolic constant that represents a TColor value, such as clBlack or clWindow. The Ident parameter is set to the symbolic name. If there is no symbolic constant defined for the color, ColorToIdent returns false.


ColorToRGB

See also 	Example

Converts a TColor value into an RGB representation of the color.

Unit

Graphics

Category

graphics utilities

extern PACKAGE int __fastcall ColorToRGB(TColor Color);

Description

Call ColorToRGB to obtain an RGB representation of a color for using with Windows API calls. ColorToRGB strips away the information that is stored in the highest order bits about which palette to use for colors that are not always available.


ColorToString

See also

Returns an AnsiString that represents the name of a TColor value.

Unit

Graphics

Category

graphics utilities

extern PACKAGE System::AnsiString __fastcall ColorToString(TColor Color);

Description

Call ColorToString to obtain an AnsiString that represents a TColor value. If there is a symbolic constant defined for the color (such as clBlack or clWindow), ColorToString returns the name of the constant. Otherwise, ColorToString returns the hex value of the color, formatted as an AnsiString.


ComClassManager

See also

Returns a TComClassManager object.

Unit

ComObj

Category

Com utilities

extern PACKAGE TComClassManager* __fastcall ComClassManager(void);

Description

Use ComClassManager to obtain a reference to the global COM class manager.


CompareMem

See also

Performs a binary comparison of two memory images.

Unit

SysUtils

Category

miscellaneous routines

extern PACKAGE bool __fastcall CompareMem(void * P1, void * P2, int Length);

Description

CompareMem performs a binary compare of Length bytes of memory referenced by P1 to that of P2.  CompareMem returns true if the memory referenced by P1 is identical to that of P2.


CompareStr

See also 	Example

Compares AnsiStrings case sensitively.

Unit

SysUtils

Category

string handling routines

extern PACKAGE int __fastcall CompareStr(const System::AnsiString S1, const System::AnsiString S2);

Description

CompareStr compares S1 to S2, with case-sensitivity. The return value is less than 0 if S1 is less than S2, 0 if S1 equals S2, or greater than 0 if S1 is greater than S2. The compare operation is based on the 8-bit ordinal value of each character and is not affected by the current Windows locale.


CompareText

See also	Example

Compares AnsiStrings by ordinal value and is not case sensitive.

Unit

SysUtils

Category

string handling routines

extern PACKAGE int __fastcall CompareText(const System::AnsiString S1, const System::AnsiString S2);

Description

CompareText compares the AnsiStrings S1 and S2 and returns 0 if they are equal. If S1 is greater than S2, CompareText returns an integer greater than 0. If S1 is less than S2, CompareText returns an integer less than 0. CompareText is not case sensitive.


CopyPalette

Creates a new palette object that matches an existing palette.

Unit

Graphics

Category

graphics utilities

extern PACKAGE HPALETTE __fastcall CopyPalette(HPALETTE Palette);

Description

Call CopyPalette to create a new Windows palette object that exactly matches an existing palette. If the Palette parameter does not refer to a valid Windows palette, or if a problem occurs while copying the palette, CopyPalette returns 0.


Cosh

Calculates the hyperbolic cosine of an angle.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall Cosh(Extended X);

Description

Use the Cosh to calculate the hyperbolic cosine of X.


Cotan

Calculates the cotangent of an angle.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall Cotan(Extended X);

Description

Call Cotan to obtain the cotangent of X. The cotangent is calculated using the formula

1 / Tan(X)

Note:	Do not call Cotan with X = 0.


CreateComObject

See also

Instantiates a single instance of a COM object.

Unit

ComObj

Category

COM utilities

virtual TComObject* __fastcall CreateComObject(const _di_IUnknown Controller);

Description

CreateComObject creates a single uninitialized object of the class associated with the CLSID specified by the ClassID parameter. CreateComObject is used to create an object of a specified type when the CLSID is known, and when the object is on a local or in-proc server.

CreateComObject is called once to create each new single instance of a class. To create multiple instance of the same class it is recommended to use a class factory.

CreateComObject returns a reference to the identifier of the interface to be used to communicate with the object. For CreateComObject this interface is of type IUnknown. To create OLE objects that return references to the IDispatch interface, use CreateOleObject.


CreateDir

See also

Creates a new directory.

Unit

SysUtils

Category

file management routines

extern PACKAGE bool __fastcall CreateDir(const System::AnsiString Dir);

Description

CreateDir creates a new directory. The return value is true if a new directory was successfully created, or false if an error occurred.


CreateGrayMappedBmp

See also

Remaps the standard gray colors in a bitmap with the system grays.

Unit

Graphics

Category

graphics utilities

extern PACKAGE HBITMAP __fastcall CreateGrayMappedBmp(HBITMAP Handle);

Description

Call CreateGrayMappedBmp to create a bitmap that uses the system gray colors (clBtnHightLight, clBtnFace, clBtnShadow and clBtnText) from a bitmap that uses standard gray scale colors (clWhite, clSilver, clGray, and clBlack). This allows an application to dynamically create images that match the user’s control panel settings, given a base image.

CreateGrayMappedBmp creates a new bitmap.  It does not alter the original bitmap, which has the handle specified by the Handle parameter.

Note:	CreateGrayMappedBmp does not work with bitmaps that have more than 256 colors. For bitmap's with more than 256 colors (8bpp), this function returns the original bitmap.


CreateMappedBmp

See also

Changes the color table in a bitmap.

Unit

Graphics

Category

graphics utilities

extern PACKAGE HBITMAP __fastcall CreateMappedBmp(HBITMAP Handle, const TColor * OldColors, const int OldColors_Size, const TColor * NewColors, const int NewColors_Size);

Description

Call CreateMappedBmp to make selective changes to the color map of a bitmap. This function replaces the colors specified by the OldColors parameter with the colors specified by the NewColors parameter and returns the handle for a new device dependent bitmap (DDB)  which uses the new color table. Handle is the handle to the bitmap whose color table should be changed. Specify the size of the color arrays in OldColors_Size and NewColorsSize. This value should be the index of the last entry in the corresponding array. The OldColors and NewColors arrays should contain the same number of elements.

CreateMappedBmp creates a new bitmap.  It does not alter the original bitmap, which has the handle specified by the Handle parameter.

Note:	CreateMappedBmp does not work with bitmaps that have more than 256 colors. For bitmap's with more than 256 colors (8bpp), this function returns the original bitmap.


CreateMappedRes

See also

Changes the color table in a bitmap resource.

Unit

Graphics

Category

graphics utilities

extern PACKAGE HBITMAP __fastcall CreateMappedRes(int Instance, char * ResName, const TColor * OldColors , const int OldColors_Size, const TColor * NewColors, const int NewColors_Size);

Description

Call CreateMappedRes to make selective changes to the color map of a resourced bitmap. This function replaces the colors specified by the OldColors parameter with the colors specified by the NewColors parameter and returns the handle for a new device dependent bitmap (DDB)  which uses the new color table. Use the Instance and ResName parameters to identify the bitmap resource whose color table should be changed.  Indicate the number of elements in the color arrays by the OldColors_Size and NewColors_Size parameters. These values should be the index of the last element in the corresponding color array, not the number of entries. The OldColors and NewColors arrays should contain the same number of elements.

Note:	CreateMappedRes does not work with bitmaps that have more than 256 colors. For bitmap's with more than 256 colors (8bpp), this function returns an instance of the original bitmap without color modifications.


CreateMessageDialog

See also

Creates a specified message dialog.

Unit

dialogs

Category

dialog and message routines

extern PACKAGE Forms::TForm* __fastcall CreateMessageDialog(const System::AnsiString Msg, TMsgDlgType DlgType, TMsgDlgButtons Buttons);

Description

Call CreateMessageDialog to create a message dialog that will be used several times in an application.  CreateMessageDialog returns a dialog of the type specified by the DlgType parameter and with the buttons indicated by the Buttons parameter.

Note:	CreateMessageDialog does not display the dialog form.  The application must display this form when it is needed.


CreateOleObject

See also

Instantiates a single instance of an OLE automation object.

Unit

ComObj

Category

COM utilities

extern PACKAGE _di_IDispatch __fastcall CreateOleObject(const System::AnsiString ClassName);

Description

CreateOleObject creates a single uninitialized object of the class specified by the ClassName parameter.  ClassName is the AnsiString representation of the Class ID (CLSID). CreateOleObject is used to create an object of a specified type when the CLSID is known, and when the object is on a local or in-proc server. Only objects that are not part of an aggregate are created using CreateOleObject.

CreateOleObject is called once to create each new single instance of a class. To create multiple instance of the same class, using a class factory is recommended.

CreateOleObject returns a reference to the identifier of the interface that can be used to communicate with the object. For CreateOleObject this interface is of type IDispatch. To create a COM object that is not an IDispatch interface, use CreateComObject.


CreateRegKey procedure
CreateRegKey

See also

Creates a registry key that is a subkey of HKEY_CLASSES_ROOT.

Unit

ComObj

Category

COM utilities

extern PACKAGE void __fastcall CreateRegKey(const System::AnsiString Key, const System::AnsiString ValueName, const System::AnsiString Value);

Description

CreateRegKey creates or opens the key specified by the Key parameter. If the key does not already exist in the registry, CreateRegKey creates it, otherwise CreateRegKey opens it. This is useful for implementing the UpdateRegistry method of a class factory.

Key points to a null-terminated AnsiString, which cannot be NULL and cannot begin with the backslash character ('\'). This subkey must be a subkey of HKEY_CLASSES_ROOT.

When the key is created, additional value and type information for the specified key can be set from the parameters passed to CreateRegKey.

ValueName points to a null-terminated AnsiString containing the name of the subkey with which a value is associated. This parameter can be null or a pointer to an empty AnsiString.

Value points to a buffer containing the data to be stored with the specified value name.

If CreateRegKey is not successful, an EOleError exception is thrown.


CreateRemoteComObject

See also

Creates a Com object on another machine and returns an IUnknown interface for it.

Unit

ComObj

Category

COM utilities

extern PACKAGE _di_IUnknown __fastcall CreateRemoteComObject(const System::WideString MachineName, const GUID &ClassID);

Description

Use CreateRemoteComObject to create an object on a remote server. CreateRemoteComObject creates a single uninitialized object of the class associated with the CLSID specified by the ClassID parameter. The MachineName parameter specifies the machine that lists the ClassID in its type library.

Usually, MachineName is the UNC name of the machine, which can be obtained by looking up the Machine Name of the machine under the Network settings in the Windows control panel. However, under some configurations of COM, MachineName is the IP address or Host name of the remote system.

CreateRemoteComObject returns a reference to the IUnknown interface for the object. Use this interface to obtain information about other interfaces supported by the object.


CurrToFMTBCD

See also

Converts a Currency value to the corresponding binary coded decimal (BCD) value.

Unit

DBCommon

Category

type conversion routines

extern PACKAGE bool __fastcall CurrToFMTBCD(System::Currency Curr, Bde::FMTBcd &BCD, int Precision, int Decimals);

Description

Use CurrToFMTBCD to convert a Currency object, such as is used by C++Builder TBCDField objects into a binary coded decimal value, such as is stored in a physical BCD database field. CurrToFMTBCD returns true if the Currency object passed as the Curr parameter is successfully converted into a BCD value which is passed out as the BCD parameter. The Precision parameter specifies the number of digits represented in the BCD value, and the Decimals parameter specifies the number of those digits that are after the decimal point.


CurrToStr

See also

Converts a Currency object to an AnsiString object.

Unit

SysUtils

Category

numeric formatting routines

extern PACKAGE System::AnsiString __fastcall CurrToStr(System::Currency Value);

Description

CurrToStr converts the Currency object given by Value to its string representation as an AnsiString object. The conversion using the ffGeneral floating point conversion rules.


CurrToStrF

See also

Converts a Currency object to an AnsiString of a specified format.

Unit

SysUtils

Category

numeric formatting routines

extern PACKAGE System::AnsiString __fastcall CurrToStrF(System::Currency Value, TFloatFormat Format, int Digits);

Description

CurrToStrF converts the Currency object given by Value to its string representation using the indicated float format convention. A call to CurrToStrF corresponds to a call to FloatToStrF with an implied precision of 19 digits.


CursorToIdent

See also

Returns the name of the predefined constant that corresponds to a cursor.

Unit

controls

Category

cursor management routines

extern PACKAGE bool __fastcall CursorToIdent(int Cursor, System::AnsiString &Ident);

Description

Use CursorToIdent to convert the cursor used by a control or one of the cursors made available by the global screen variable into the name of the corresponding constant.  Pass the cursor value as the Cursor parameter.  CursorToIdent returns the constant name as the Ident parameter.  If the cursor does not have an associated constant (for example, a custom cursor), CursorToIdent returns false.

To obtain an AnsiString representation of the cursor, even if there is no built-in cursor constant for it, use the CursorToString function.

CursorToIdent can be used to identify the current cursor in a list of possible cursor constants that is built using GetCursorValues.


CursorToString

See also

Returns the AnsiString representation of a cursor.

Unit

controls

Category

cursor management routines

extern PACKAGE System::AnsiString __fastcall CursorToString(TCursor Cursor);

Description

Use CursorToString to convert the cursor used by a control or one of the cursors made available by the global screen variable into an AnsiString that can be displayed to the user.  Pass the cursor value as the Cursor parameter.  If there is a predefined constant for the cursor, CursorToString returns the constant name.  If the cursor does not have an associated constant (for example, a custom cursor), CursorToString returns the AnsiString representation of the cursor’s numeric value.

To obtain a AnsiString representation of the cursor only if there is a built-in cursor constant, use CursorToIdent.


CycleToRad

See also

Converts an angle measurement from cycles to radians.

Unit

Math

Category

measurement conversion routines

extern PACKAGE Extended __fastcall CycleToRad(Extended Cycles);

Description

CycleToRad converts angles measured in cycles into radians, where

radians = 2pi * cycles.


DatabaseError procedure
DatabaseError

See also

Creates and throws an EDatabaseError exception.

Unit

DB

Category

exception handling routines

extern PACKAGE void __fastcall DatabaseError(const System::AnsiString Message);

Description

Call DatabaseError to throw an EDatabaseError exception, using Message as the text for the exception. Calling DatabaseError rather than creating and throwing the exception directly in code reduces the overall code size of the application.


DatabaseErrorFmt procedure
DatabaseErrorFmt

See also

Creates and throws an EDatabaseError exception with a formatted error message.

Unit

DB

Category

exception handling routines

extern PACKAGE void __fastcall DatabaseErrorFmt(const System::AnsiString Message, const System::TVarRec * Args, const int Args_Size);

Description

Call DatabaseError to throw an EDatabaseError exception. The error message for the exception is assembled from the Format AnsiString specified by the Message parameter and applying the Args parameter. Call DatabaseErrorFmt rather than creating and throwing the exception directly in code to reduce the overall code size of the application.


Date

See also	Example

Returns the current date.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall Date(void);

Description

Use Date to obtain the current date as a TDateTime value.


DateTimeToFileDate

See also

Converts a TDateTime object to a DOS date-and-time value.

Unit

SysUtils

Category

date/time routines

extern PACKAGE int __fastcall DateTimeToFileDate(System::TDateTime DateTime);

Description

The FileAge, FileGetDate, and FileSetDate routines operate on DOS date-and-time values, and the Time field of a TSearchRec used by the FindFirst and FindNext functions contains a DOS date-and-time value.


DateTimeToStr

See also	Example

Converts a TDateTime object to an AnsiString object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::AnsiString __fastcall DateTimeToStr(System::TDateTime DateTime);

Description

If DateTime parameter does not contain a date value, the date displays as 00/00/00. If the DateTime parameter does not contain a time value, the time displays as 00:00:00 AM.To change how the AnsiString is formatting, change some of the date and time typed constants.


DateTimeToString procedure
DateTimeToString

See also

Converts a TDateTime object to an AnsiString using the specified Format.

Unit

SysUtils

Category

date/time routines

extern PACKAGE void __fastcall DateTimeToString(System::AnsiString &Result, const System::AnsiString Format, System::TDateTime DateTime);

Description

DateTimeToString converts the TDateTime object given by DateTime using the format AnsiString given by Format into the AnsiString variable given by Result. For Formats supported, refer to the description of the FormatDateTime function.


DateTimeToSystemTime procedure
DateTimeToSystemTime

See also

Converts a TDateTime object into the Win32 API's TSystemTime format.

Unit

SysUtils

Category

date/time routines

extern PACKAGE void __fastcall DateTimeToSystemTime(System::TDateTime DateTime, _SYSTEMTIME &SystemTime);

Description

Use DateTimeToSystemTime to convert a TDateTime object into a TSystemTime value to use with a Windows 32 API call.


DateTimeToTimeStamp

See also

Converts a TDateTime object into the corresponding TTimeStamp structure.

Unit

SysUtils

Category

date/time routines

extern PACKAGE TTimeStamp __fastcall DateTimeToTimeStamp(System::TDateTime DateTime);

Description

Call DateTimeToTimeStamp to convert a TDateTime object into a TTimeStamp structure. TDateTime values represent time as the number of days (including fractional days) that have elapsed since 12:00 am on December 30, 1899. TTimeStamp represents time as separate date and time values, where the date is the number of calandar days since the start of the current calandar (that is, January 1, 0001 would have a value of 1), and time is the number of milliseconds since midnight.


DateToStr

See also	Example

Converts a TDateTime object to an AnsiString object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::AnsiString __fastcall DateToStr(System::TDateTime Date);

Description

Use DateToStr to obtain an AnsiString representation of a date value that can be used for display purposes. The conversion uses the format specified by the ShortDateFormat global variable.


DayOfWeek

See also	Example

Returns the day of the week for a specified date.

Unit

SysUtils

Category

date/time routines

extern PACKAGE int __fastcall DayOfWeek(System::TDateTime Date);

Description

DayOfWeek returns the day of the week of the specified date as an integer between 1 and 7. Sunday is the first day of the week and Saturday is the seventh.


DBError procedure
DBError

See also

Creates and throws an EDatabaseError exception with a resourced error message.

Unit

DB

Category

exception handling routines

extern PACKAGE void __fastcall DBError(Word Ident);

Description

Call DBError to throw an EDatabaseError exception, where Ident is the resource ID for the text of the error message. Call DBError rather than creating and throwing the exception directly in code reduces the overall code size of the application.


DBErrorFmt procedure
DBErrorFmt

See also

Creates and throws EDatabaseError exception with a resourced formatted error message.

Unit

DB

Category

exception handling routines

extern PACKAGE void __fastcall DBErrorFmt(Word Ident, const System::TVarRec * Args, const int Args_Size);

Description

Call DBErrorFmt to throw an EDatabaseError exception. The error message for the exception is assembled by loading the format string with the resource identifier specified by the Ident parameter and formatting it using the Args parameter. Call DBErrorFmt rather than creating and throwing the exception directly in code to reduce the overall code size of the application.


DBIError procedure
DBIError

See also

Creates and throws an EDBEngineError exception for an error code returned by the Borland Database Engine (BDE).

Unit

DBTables

Category

BDE support routines

extern PACKAGE void __fastcall DbiError(Word ErrorCode);

Description

Call DBIError to throw an EDBEngineError for the error code passed as the ErrorCode parameter. DBIError obtains the error string from the BDE for the error and throws an EDBEngineError exception.


DecodeTime

See also	Example

Breaks a TDateTime object into hours, minutes, seconds, and milliseconds.

Unit

SysUtils

Category

date/time routines

extern PACKAGE void __fastcall DecodeTime(System::TDateTime Time, Word &Hour, Word &Min, Word &Sec, Word &MSec);

Description

DecodeTime breaks the object specified as the Time parameter into hours, minutes, seconds, and milliseconds.


DegToRad

See also

Returns the value of a degree measurement expressed in radians.

Unit

Math

Category

measurement conversion routines

extern PACKAGE Extended __fastcall DegToRad(Extended Degrees);

Description

Use DegToRad to convert angles expressed in degrees to the corresponding value in radians, where

radians = degrees(pi/180).


DeleteFile

Example

Deletes a file from disk, and returns false if the delete fails.

Unit

SysUtils

Category

file management routines

extern PACKAGE bool __fastcall DeleteFile(const System::AnsiString FileName);

Description

DeleteFile erases the file named by FileName from the disk. If the file cannot be deleted or does not exist, the function returns false.


DeleteRegKey procedure
DeleteRegKey

See also

Deletes a single key that is a subkey of HKEY_CLASSES_ROOT from the system registry.

Unit

ComObj

Category

COM utilities

extern PACKAGE void __fastcall DeleteRegKey(const System::AnsiString Key);

Description

Use DeleteRegKey to update the system registry. This is useful for implementing the UpdateRegistry method of a class factory.

DeleteRegKey deletes the subkey of HKEY_CLASSES_ROOT that is passed in as the Key parameter. Key must point to a a null-terminated AnsiString, which specifies the name of the key to delete, and cannot be NULL. The Key to delete must not have subkeys.

If DeleteRegKey succeeds it removes the entire specified key from the registry, including all of its values. An exception is thrown if it fails.


DestroyMetaPict procedure
DestroyMetaPict

See also

Frees a metafile resource given its handle.

Unit

OleCtnrs

Category

Windows controls utilities

extern PACKAGE void __fastcall DestroyMetaPict(int MetaPict);

Description

Call DestroyMetaPict to free the metafile obtained using the GetIconMetaPict method of TOleContainer.

You do not need to use DestroyMetaPict to free metafiles represented using TMetafile. These are freed automatically when the TMetafile instance is destroyed.  However, if you assign a new value to the Handle property of TMetafile, thereby replacing its old metafile, you must free the old metafile by calling DestroyMetaPict.


DirectoryExists

See also

Determines whether a specified directory exists.

Unit

FileCtrl

Category

file management routines

extern PACKAGE bool __fastcall DirectoryExists(const System::AnsiString Name);

Description

Call DirectoryExists to determine whether the directory specified by the Name parameter exists. If the directory exists, the function returns true. If the directory does not exist, the function returns false.

If a full path name is entered, DirectoryExists searches for the directory along the designated path. Otherwise, the Name parameter is interpreted as a relative path name within the current directory.


DiskFree

See also	Example

Returns the number of free bytes on a specified drive.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall DiskFree(Byte Drive);

Description

DiskFree returns the number of free bytes on the specified drive number, where 0 = Current, 1 = A, 2 = B, and so on.

DiskFree returns -1 if the drive number is invalid.


DiskSize

See also	Example

Returns the size, in bytes, of the specified drive.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall DiskSize(Byte Drive);

Description

DiskSize returns the size in bytes of the specified drive number, where 0 = Current, 1 = A, 2 = B, etc. DiskSize returns -1 if the drive number is invalid.


DisposeStr procedure
DisposeStr

See also

Disposes of an AnsiString pointer that was allocated using NewStr.

Unit

SysUtils

Category

backward compatibility routines

extern PACKAGE void __fastcall DisposeStr(System::PAnsiString P);

Description

DisposeStr is only provided for backward compatibility with existing code that allocated an AnsiString using NewStr. Both DisposeStr and NewStr are obsolete.


DoubleDecliningBalance

Calculates the depreciation of an asset using the double-declining balance method.

Unit

Math

Category

Buisness and Finance routines

extern PACKAGE Extended __fastcall DoubleDecliningBalance(Extended Cost, Extended Salvage, int Life, int Period);

Description

DoubleDecliningBalance determines accelerated depreciation values for an asset, given the initial cost, life expectancy, end value, and depreciation period.


EncodeDate

See also	Example

Returns a TDateTime object for a specified Year, Month, and Day.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall EncodeDate(Word Year, Word Month, Word Day);

Description

EncodeDate returns a TDateTime object from the values specified as the Year, Month, and Day parameters.

The year must be between 1 and 9999.

Valid Month values are 1 through 12.

Valid Day values are 1 through 28, 29, 30, or 31, depending on the Month value. For example, the possible Day values for month 2 (February) are 1 through 28 or 1 through 29, depending on whether or not the Year value specifies a leap year.

If the specified values are not within range, an EConvertError exception is thrown. The resulting value is one plus the number of days between 12/30/1899 and the given date.


EncodeTime

See also	Example

Returns a TDateTime object for a specified Hour, Min, Sec, and MSec.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall EncodeTime(Word Hour, Word Min, Word Sec, Word MSec);

Description

If the value of the Time24Hour typed constant is false, valid Hour values are 0 through 12. If the value of Time24Hour is true, valid Hour values are 0 through 23.

Valid Min and Sec values are 0 through 59. Valid MSec values are 0 through 999.

If the specified values are not within range, an EConvertError exception is thrown. The resulting value is a number between 0 (inclusive) and 1 (not inclusive) that indicates the fractional part of a day given by the specified time. The value 0 corresponds to midnight, 0.5 corresponds to noon, 0.75 corresponds to 6:00 pm, etc.


EnumModules procedure
EnumModules

See also

Enumerates all modules in an application.

Unit

System

Category

package support routines

extern PACKAGE void __fastcall EnumModules(TEnumModuleFunc Func, void * Data);

procedure EnumModules(Func: TEnumModuleFunc; Data: Pointer);

Description

EnumModules enumerates the EXE and all packages in an application by passing the handle of the EXE and then of each package, in turn, to a user-defined callback function. EnumModules continues until the last module in the application is enumerated, or until the callback function returns false. The parameters to EnumModules areas follows:

Parameter	Meaning
TEnumModulesFunc	The procedure-instance address of the callback function.
Data	A 32-bit user-defined value that is passed to the callback function.


EnumResourceModules procedure
EnumResourceModules

See also

Enumerates all resource modules in an application.

Unit

System

Category

package support routines

extern PACKAGE void __fastcall EnumResourceModules(TEnumModuleFunc Func, void * Data);

procedure EnumResourceModules(Func: TEnumModuleFunc; Data: Pointer);

Description

EnumResourceModules enumerates all of the instance handles associated with resources for the current program. The instance handle (HINSTANCE) of each resource is passed to a user-defined callback function. EnumResourceModules continues until the last resource module in the application is enumerated, or until the callback function returns false. The parameters to EnumResourceModules are as follows:

Parameter	Meaning
TEnumModulesFunc	The procedure-instance address of the callback function.
Data	A 32-bit user-defined value that is passed to the callback function.


ExceptAddr

See also

Returns the address at which the current exception was thrown.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE void * __fastcall ExceptAddr(void);

Description

Use ExceptAddr to obtain the address at which an exception was thrown. If there is no current exception, ExceptAddr returns NULL.


ExceptionErrorMessage

See also

Formats a standard error message.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE int __fastcall ExceptionErrorMessage(System::TObject* ExceptObject, void * ExceptAddr, char * Buffer, int Size);

Description

Call ExceptionErrorMessage to assemble an error message that indicates the object associated with the current exception and the location at which the exception was thrown. The assembled message is written into the buffer provided by the Buffer parameter. Specify the size of this buffer using the Size parameter.

ExceptionErrorMessage returns the number of bytes in the assembled error message.


ExceptObject

See also

Returns a reference to the object associated with the current exception.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE System::TObject* __fastcall ExceptObject(void);

Description

ExceptObject returns a reference to the current exception object -- that is, the descendant of Exception that is associated with the current exception. If there is no current exception, ExceptObject returns NULL.


ExpandFileName

See also	Example

Returns the full path of Filename.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExpandFileName(const System::AnsiString FileName);

Description

ExpandFileName converts the relative file name into a fully qualified path name by merging in the current drive and directory. A fully qualified path name includes the drive letter and any directory and subdirectories in addition to the file name and extension. ExpandFileName does not verify that the resulting fully qualified path name refers to an existing file, or even that the resulting path exists.


ExpandUNCFileName

See also

Returns the full path of FileName with the network drive portion in UNC format.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExpandUNCFileName(const System::AnsiString FileName);

Description

ExpandUNCFileName returns an AnsiString containing a fully qualified path name for the file passed in the FileName. A fully qualified path name includes the drive portion of the filename in the UNC format '\\<servername>\<sharename>' if the drive letter is mapped to a network resource instead of a local drive and any directory and subdirectories in addition to the file name and extension.

C++Builder programs can use this function to store filenames that are independent of a particular user's drive letter mappings.


ExtractFileDir

See also

Extracts the drive and directory parts from FileName.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractFileDir(const System::AnsiString FileName);

Description

The resulting AnsiString is a directory name suitable for passing to the CreateDir, GetCurrentDir, RemoveDir, and SetCurrentDir functions. The resulting AnsiString is empty if FileName contains no drive and directory parts.

Note:	This function works for multi-byte character systems (MBCS).


ExtractFileDrive

See also

Returns the drive portion from FileName.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractFileDrive(const System::AnsiString FileName);

Description

ExtractFileDrive returns an AnsiString containing the 'drive' portion of a fully qualified path name for the file passed in the FileName. For file names with drive letters, the resulting AnsiString is in the form '<drive>:'. For file names with a UNC path the resulting AnsiString is in the form '\\<servername>\<sharename>'. If the given path contains neither style of path prefix, the result is an empty AnsiString.

C++Builder programs can use this function to store filenames that are independent of a particular user's drive letter mappings.


ExtractFileExt

See also

Returns the extension portions of FileName.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractFileExt(const System::AnsiString FileName);

Description

The resulting AnsiString includes the period character that separates the name and extension parts. The resulting AnsiString is empty if the given filename has no extension. For example, the following code returns the extension from a file name:

MyFilesExtension = ExtractFileExt(MyFileName);

Note:	This function works for multi-byte character systems (MBCS).


ExtractFileName

See also

Extracts the name and extension parts of FileName.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractFileName(const System::AnsiString FileName);

Description

The resulting AnsiString is the leftmost characters of FileName, starting with the first character after the colon or backslash that separates the path information from the name and extension. The resulting AnsiString is equal to FileName if FileName contains no drive and directory parts.

Note:	This function works for multi-byte character systems (MBCS).


ExtractFilePath

See also	Example

Returns the drive and directory portions of FileName.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractFilePath(const System::AnsiString FileName);

Description

The resulting AnsiString is the rightmost characters of FileName, up to and including the colon or backslash that separates the path information from the name and extension. The resulting AnsiString is empty if FileName contains no drive and directory parts.

Note:	This function works for multi-byte character systems (MBCS).


ExtractRelativePath

See also

Returns a relative path name, relative to a specific base directory.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractRelativePath(const System::AnsiString BaseName, const System::AnsiString DestName);

Description

Call ExtractRelativePath to convert a fully qualified path name into a relative path name.  The DestName parameter specifies the path and file name to be converted.  BaseName is the fully qualified name of the base directory to which the returned path name should be relative.

ExtractRelativePath strips out common path directories and inserts '..\' for each level up from the BaseName.


ExtractShortPathName

See also

Converts a file name to the short 8.3 form.

Unit

SysUtils

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall ExtractShortPathName(const System::AnsiString FileName);

Description

ExtractShortPathName converts the file name, FileName, to the short 8.3 form. ExtractShortPathName returns an empty AnsiString if the file or directory does not exist.

The first parameter, FileName, can be a full path name. For example, ExtractShortPathName would convert the full path name:

C:\Program Files\Borland\CBuilder\Bin\Bcb.exe

to the short form:

C:\Progra~1\Borland\CBuilder\Bin\Bcb.exe


FileAge

Returns the date-and-time stamp of the specified file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileAge(const System::AnsiString FileName);

Description

The return value can be converted to a TDateTime object using the FileDateToDateTime function. The return value is -1 if the file does not exist.


FileClose procedure
FileClose

See also

Closes a specified file.

Unit

SysUtils

Category

file management routines

extern PACKAGE void __fastcall FileClose(int Handle);

Description

FileClose closes the specified file. For more information on which file handling routines to use see FileOpen.


FileCreate

See also	Example

Creates a new file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileCreate(const System::AnsiString FileName);

Description

FileCreate creates a new file of the specified name. If the return value is positive, the function was successful and the value is the file handle of the new file. A return value of -1 indicates that an error occurred.


FileDateToDateTime

See also

Converts a DOS date-time value to TDateTime object.

Unit

SysUtils

Category

file management routines

extern PACKAGE System::TDateTime __fastcall FileDateToDateTime(int FileDate);

Description

The FileAge, FileGetDate, and FileSetDate routines operate on DOS date-time values, and the Time field of a TSearchRec used by the FindFirst and FindNext functions contains a DOS date-time value.


FileExists

See also	Example

Tests if a specified file exists.

Unit

SysUtils

Category

file management routines

extern PACKAGE bool __fastcall FileExists(const System::AnsiString FileName);

Description

FileExists returns true if the file specified by FileName exists. If the file does not exist, FileExists returns false.


FileGetAttr

See also

Returns the file attributes of FileName.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileGetAttr(const System::AnsiString FileName);

Description

The attributes can be examined by AND-ing the attributes with the constants defined in TSearchRec. A return value of -1 indicates that an error occurred.


FileGetDate

See also

Returns a DOS date-time stamp for the specified file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileGetDate(int Handle);

Description

The return value is -1 if the handle is invalid. The FileDateToDateTime function can be used to convert the returned value to a TDateTime object.


FileOpen

See also	Example

Opens a specified file using the specified access mode.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileOpen(const System::AnsiString FileName, int Mode);

Description

The access mode value is constructed by OR-ing one of the fmOpen constants with one of the fmShare constants defined by the File open mode constants. If the return value is positive, the function was successful and the value is the file handle of the opened file. A return value of -1 indicates that an error occurred.


FileRead

See also	Example

Reads a specified number of bytes from a file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileRead(int Handle, void *Buffer, int Count);

Description

FileRead reads Count bytes from the Handle into the buffer. The function result is the actual number of bytes read, which may be less than Count. The Handle that is passed to FileRead must be opened with FileOpen or FileCreate. Do not mix routines that take or return file handles with those that use Pascal file variables (typically seen as var F).


FileSearch

See also	Example

Searchs a specified DOS path for a file.

Unit

SysUtils

Category

file management routines

extern PACKAGE System::AnsiString __fastcall FileSearch(const System::AnsiString Name, const System::AnsiString DirList);

Description

FileSearch searches through the directories passed in DirList for a file named Name. DirList should be in the same format as a DOS path: directory names separated by semicolons. If FileSearch locates a file matching Name, it returns an AnsiString containing a fully-qualified path name for that file. If no matching file exists, FileSearch returns an empty AnsiString.


FileSeek

See also	Example

Positions the current file pointer within a previously opened file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileSeek(int Handle, int Offset, int Origin);

Description

Handle contains the file handle. The Handle that is passed to FileSeek must have been opened with FileOpen or FileCreate.

Offset specifies the number of bytes from Origin where the file pointer should be positioned. Origin is a code with three possible values, denoting the beginning of the file, the end of the file, and the current position of the file pointer.

Origin	Action
0	The file pointer is positioned Offset bytes from the beginning of the file.
1	The file pointer is positioned Offset bytes from its current position.
2	The file pointer is positioned Offset bytes from the end of the file.
If FileSeek is successful, it returns the new position of the file pointer; otherwise, it returns -1.


FileSetAttr

See also

Sets the file attributes of a specified file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileSetAttr(const System::AnsiString FileName, int Attr);

Description

FileSetAttr sets the file attributes of the file given by FileName to the value given by Attr. The attribute value is formed by OR-ing the appropriate TSearchRec type constants. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


FileSetDate

See also

Sets the DOS time stamp for a specified file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileSetDate(int Handle, int Age);

Description

FileSetDate sets the DOS date-time stamp of the file given by Handle to the value given by Age. The DateTimeToFileDate function can be used to convert a TDateTime object to a DOS date-time stamp. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


FileWrite

See also

Writes the contents of a buffer to the current position in a file.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FileWrite(int Handle, const void *Buffer, int Count);

Description

FileWrite writes Count bytes to the file given by Handle from the buffer specified by Buffer. The return value is the number of bytes actually written, or -1 if an error occurred.


FinalizePackage procedure
FinalizePackage

See also

Finalizes the specified package .DPL.

Unit

SysUtils

Category

package support routines

extern PACKAGE void __fastcall FinalizePackage(Windows::HINST Module);

Description

Most applications do not need to call FinalizePackage, because UnloadPackage calls FinalizePackage internally. FinalizePackage executes any finalization code in the specified package.


FindClass

See also

Finds and returns a class that is derived from TPersistent.

Unit

classes

Category:

class handling routines

extern PACKAGE System::TMetaClass * __fastcall FindClass(const System::AnsiString ClassName);

Description

Call FindClass to locate a class type by name.  FindClass searches the classes that the streaming system knows about.  Form classes and component classes that are referenced in a form declaration (instance variables) are automatically registered with the streaming system.  Other classes can be registered (with a call to RegisterClasses) so that the streaming system will recognize that class in a stream and know how to construct it.

If the requested class name cannot be found, FindClass throws an exception.


FindClassHInstance

See also

Returns the instance handle for the module in which a class type is defined.

Unit

system

Category:

streaming utilities

extern PACKAGE int __fastcall FindClassHInstance(TMetaClass * ClassType);

Description

FindClassInstance finds the HINSTANCE of the EXE or DLL that “owns”, or contains, the runtime type information (RTTI) and the Virtual Method Table (VMT) for the specified class passed in as the Class Type parameter. When reading a component (which is a type), this information is needed in order to be able to load the .dfm file (resources) associated with that component. The VCL streaming system uses FindClassHInstance for this purpose.

FindClassInstance returns 0 if the instance is not found. Otherwise it returns the class owner’s HINSTANCE.


FindClose procedure
FindClose

See also 	Example

Releases memory allocated by FindFirst.

Unit

SysUtils

Category:

file management routines

extern PACKAGE void __fastcall FindClose(TSearchRec &F);

Description

FindClose terminates a FindFirst/FindNext sequence.


FindCmdLineSwitch

See also

Determines whether an AnsiString was passed as a command line argument to the application.

Unit

SysUtils

Category

command line utilities

extern PACKAGE bool __fastcall FindCmdLineSwitch(const System::AnsiString Switch, const TSysCharSet &SwitchChars, bool IgnoreCase);

Description

FindCmdLineSwitch determines whether the AnsiString in the Switch parameter was passed as a command line argument to the application. SwitchChars identifies valid argument-delimiter characters (e.g., "-" and "/" are common delimiters). The IgnoreCase parameter controls whether a case-sensistive or case-insensitive search is performed.


FindControl

See also

Returns the windowed control whose window is identified by the specified window handle.

Unit

Controls

Category

Windows controls utilities

extern PACKAGE TWinControl* __fastcall FindControl(HWND Handle);

Description

Call FindControl to access the windowed control whose window is identified by the Handle parameter. If Handle is not the handle of the window of a windowed control, FindControl returns NULL.


FindDragTarget

See also

Returns the control at a specified screen coordinate.

Unit

Controls

Category

drag and drop routines

extern PACKAGE TControl* __fastcall FindDragTarget(const tagPOINT &Pos, bool AllowDisabled);

Description

Call FindDragTarget to determine the potential drag-and-drop target currently under the mouse. FindDragTarget returns the control at the position specified by the Pos parameter. If there is not control at the specified position, FindDragTarget returns NULL. The AllowDisabled parameter determines whether the search includes disabled controls.

If FindDragTarget returns a control, this does not mean that the control will necessarily accept the dragged object. The control will only accept the dragged object if it has an OnDragOver event handler that accepts the object.


FindFirst

See also	Example

Searches for the first instance of a file name with a given set of attributes in a specified directory.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FindFirst(const System::AnsiString Path, int Attr, TSearchRec &F);

Description

FindFirst searches the directory specified by Path for the first file that matches the file name implied by Path and the attributes specified by the Attr parameter. The result is returned in the F parameter. Use the fields of this search record to extract the information needed. FileFirst returns 0 if a file was successfully located, otherwise, it returns a Windows error code.

The Path constant parameter is the directory and file name mask, including wildcard characters. For example, 'c:\test\*.*' specifies all files in the C:\TEST directory).

The Attr parameter specifies the special files to include in addition to all normal files. Choose from these file attribute constants when specifying the Attr parameter:

Constant	Value	Description
faReadOnly	$00000001	Read-only files
faHidden	$00000002	Hidden files
faSysFile	$00000004	System files
faVolumeID	$00000008	Volume ID files
faDirectory	$00000010	Directory files
faArchive	$00000020	Archive files
faAnyFile	$0000003F	Any file
Attributes can be combined by adding their constants or values. For example, to search for read-only and hidden files in addition to normal files, pass (faReadOnly | faHidden) as the Attr parameter.

Note:	FindFirst allocates resources (memory) which must be released by calling FindClose.


FindHInstance

See also

Returns the instance handle of the module that contains a specified address.

Unit

system

Category:

streaming utilities

extern PACKAGE int __fastcall FindHInstance(void * Address);

Description

Use FindHInstance to obtain the HINSTANCE of the module that “owns”, or contains, the address specified by the Address parameter. If no HINSTANCE is found for that address, FindHInstance returns 0.


FindNext

See also	Example

Returns the next entry matching the name and attributes specified in a previous call to FindFirst.

Unit

SysUtils

Category

file management routines

extern PACKAGE int __fastcall FindNext(TSearchRec &F);

Description

FindNext returns the next entry that matches the name and attributes specified in a previous call to FindFirst. The search record must be one that was passed to FindFirst. The return value is zero if the function was successful. Otherwise the return value is a Windows error code.


FindResourceHInstance

See also

Returns the instance handle of the resource module associated with a specified HINSTANCE.

Unit

system

Category:

streaming utilities

extern PACKAGE int __fastcall FindResourceHInstance(int Instance);

Description

When a C++Builder application that uses the VCL starts up, it checks the locale of the local system. If it finds any resource modules with the same name as the .EXE, .DLL, or .DPL files it is using, it checks the extension on those modules. If the extension of the resource module matches the language and country of the system locale, the application uses the resources in that resource module instead of the resources in the executable, DLL, or package.

FindResourceHInstance finds and returns the HINSTANCE of the resource module associated with the executable, DLL, or package identified by the Instance parameter.

FindResourceHInstance returns 0 upon failure.

Note:	The Instance parameter must be a valid HINSTANCE.


FindVCLWindow

See also

Returns the windowed control, if any, at the specified location.

Unit

Controls

Category

mouse handling utilities

extern PACKAGE TWinControl * __fastcall FindVCLWindow(const tagPOINT &Pos);

Description

Call FindVCLWindow to locate the windowed control under a certain point.  For example, use FindVCLWindow to identify the windowed control that is under the mouse from another control that has captured the mouse.  The Pos parameter specifies the location which must be over the returned windowed control.  If there is no windowed control under the Pos parameter, FindVCLWindow returns NULL.


FloatToDecimal procedure
FloatToDecimal

Converts a floating-point value to a decimal representation.

Unit

SysUtils

Category

Floating point conversion routines

extern PACKAGE void __fastcall FloatToDecimal(TFloatRec &Result, const void *Value, TFloatValue ValueType, int Precision, int Decimals);

Description

FloatToDecimal converts a floating-point value to a decimal representation that is suited for further formatting.

The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter.

For values of type Extended, the Precision parameter specifies the requested number of significant digits in the result--the allowed range is 1..18. For values of type Currency, the Precision parameter is ignored, and the implied precision of the conversion is 19 digits.

The Decimals parameter specifies the requested maximum number of digits to the left of the decimal point in the result. Precision and Decimals together control how the result is rounded. To produce a result that always has a given number of significant digits regardless of the magnitude of the number, specify 9999 for the Decimals parameter.

The result of the conversion is stored in the specified TFloatRec record as follows:

Field	Value
Exponent	Contains the magnitude of the number, i.e. the number of significant digits to the right of the decimal point. The Exponent field is negative if the absolute value of the number is less than one. If the number is a NAN (not-a-number), Exponent is set to -32768. If the number is INF or -INF (positive or negative infinity), Exponent is set to 32767.
Negative	True if the number is negative, false if the number is zero or positive.
Digits	Contains up to 18 (for type Extended) or 19 (for type Currency) significant digits followed by a null terminator. The implied decimal point (if any) is not stored in Digits. Trailing zeros are removed, and if the resulting number is zero, NAN, or INF, Digits contains nothing but the null terminator.


FloatToStr

See also

Converts a floating point value to an AnsiString.

Unit

SysUtils

Category

Floating point conversion routines

extern PACKAGE System::AnsiString __fastcall FloatToStr(Extended Value);

Description

FloatToStr converts the floating-point value given by Value to its AnsiString representation. The conversion uses general number format with 15 significant digits.

For further details, see the description of the FloatToStrF function.


FloatToStrF

See also

Converts a floating point value to an AnsiString, using a specified Format, Precision, and Digits.

Unit

SysUtils

Category

Floating point conversion routines

extern PACKAGE System::AnsiString __fastcall FloatToStrF(Extended Value, TFloatFormat Format, int Precision, int Digits);

Description

FloatToStrF converts the floating-point value given by Value to its AnsiString representation.

The Format parameter controls the format of the resulting AnsiString.

The Precision parameter specifies the precision of the given value. It should be 7 or less for values of type Single, 15 or less for values of type Double, and 18 or less for values of type Extended.

The meaning of the Digits parameter depends on the particular format selected.

The possible values of the Format parameter, and the meaning of each, are described below.

Value	Meaning
ffGeneral	General number format. The value is converted to the shortest possible decimal string using fixed or scientific format. Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format, and the Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).
ffExponent	Scientific format. The value is converted to a string of the form "-d.ddd...E+dddd". The resulting string starts with a minus sign if the number is negative, and one digit always precedes the decimal point. The total number of digits in the resulting string (including the one before the decimal point) is given by the Precision parameter. The "E" exponent character in the resulting string is always followed by a plus or minus sign and up to four digits. The Digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).
ffFixed	Fixed point format. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative, and at least one digit always precedes the decimal point. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18. If the number of digits to the left of the decimal point is greater than the specified precision, the resulting value will use scientific format.
ffNumber	Number format. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The ffNumber format corresponds to the ffFixed format, except that the resulting string contains thousand separators.
ffCurrency	Currency format. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, and DecimalSeparator global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panels. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18.
For all formats, the actual characters used as decimal and thousand separators are obtained from the DecimalSeparator and ThousandSeparator global variables.

If the given value is a NAN (not-a-number), the resulting string is 'NAN'. If the given value is positive infinity, the resulting string is 'INF'. If the given value is negative infinity, the resulting string is '-INF'.


FloatToText

See also

Converts a floating-point value to an unterminated character string, using a specified Format, Precision and Digits.

Unit

SysUtils

Category

Floating point conversion routines

extern PACKAGE int __fastcall FloatToText(char * Buffer, const void *Value, TFloatValue ValueType, TFloatFormat Format, int Precision, int Digits);

Description

FloatToText converts the given floating-point value to its decimal representation using the specified format, precision, and digits. The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter. The resulting string of characters is stored in the given buffer, and the returned value is the number of characters stored. The resulting string is not null-terminated.


FloatToTextFmt

See also

Converts a floating-point value to to an unterminated character string, using a specified format.

Unit

SysUtils

Category

Floating point conversion routines

extern PACKAGE int __fastcall FloatToTextFmt(char * Buffer, const void *Value, TFloatValue ValueType, char * Format);

Description

The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter. The resulting string of characters is stored in the given buffer, and the returned value is the number of characters stored. The resulting string is not null-terminated.

Formats supported are described as part of the FormatFloat function.


Floor

Rounds variables toward negative infinity.

Unit

Math

Category

arithmetic routines

extern PACKAGE int __fastcall Floor(Extended X);

Description

Call Floor to obtain the highest integer less than or equal to X. For example:

Floor(-2.8) = -3

Floor(2.8) = 2

Floor(-1.0) = -1

Note:	The absolute value of X must be less than MaxInt.


FMTBCDToCurr

See also

Converts a binary coded decimal value (BCD) to the corresponding Currency object.

Unit

DBCommon

Category

type conversion routines

extern PACKAGE bool __fastcall FMTBCDToCurr(const Bde::FMTBcd &BCD, System::Currency &Curr);

Description

Use FMTBCDToCurr to convert a binary coded decimal value, such as is stored in a physical BCD database field, into a Currency object, which is the representation used by VCL TBCDField objects. FMTBCDToCurr returns true if the BCD value passed as the BCD parameter is successfully converted into a Currency object which is passed out as the Curr parameter.


FmtLoadStr

See also

Returns formatted output using a resourced format AnsiString.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE System::AnsiString __fastcall FmtLoadStr(int Ident, const System::TVarRec * Args, const int Args_Size);

Description

FmtLoadStr loads an AnsiString from a program's resource string table and uses that string, plus the Args array, as a parameter to Format. Ident is the string resource ID of the desired format string. Result is the output of Format.

For information on the format strings, see Format Strings.


FmtStr procedure
FmtStr

See also

Assembles a formatted AnsiString using a format AnsiString and a series of array arguments.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE void __fastcall FmtStr(System::AnsiString &Result, const System::AnsiString Format, const System::TVarRec * Args, const int Args_Size);

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the format AnsiString Format; the results are returned in the parameter StrResult.

For information on the format strings, see Format Strings.


ForceDirectories procedure
ForceDirectories

See also	Example

Creates all the directories along a directory path if they do not already exist.

Unit

FileCtrl

Category

file management routines

extern PACKAGE void __fastcall ForceDirectories(System::AnsiString Dir);

Description

DOS and Windows only allow directories to be created one at a time. For example, to create the C:\APPS\SALES\LOCAL directory, the APPS and SALES directories must exist before the LOCAL directory can be created. Use ForceDirectories to create a directory and all parent directories that do not already exist.


Format

See also	Example

Returns a formatted AnsiString assembled from a format string and a series of array arguments.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE System::AnsiString __fastcall Format(const System::AnsiString Format, const System::TVarRec* Args, const int Args_Size);

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the format string Format; the results are returned in the function result as an AnsiString.

For information on the format strings, see Format Strings.


FormatBuf

See also

Formats the arguments from an array, placing the result in Buffer.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE Cardinal __fastcall FormatBuf(void *Buffer, Cardinal BufLen, const void *Format, Cardinal FmtLen, const System::TVarRec * Args, const int Args_Size);

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the format string Format (whose length is given by FmtLen); the results are returned in Buffer (whose length is given by BufLen). The function returns the length, in bytes, of the resulting string.

For information on the format strings, see Format Strings.


FormatCurr

See also

Formats a Currency object.

Unit

SysUtils

Category

numeric formatting routines

extern PACKAGE System::AnsiString __fastcall FormatCurr(const System::AnsiString Format, System::Currency Value);

Description

FormatCurr formats the Currency object given by Value using the format string given by Format. For further details, see the description of the FormatFloat function.


FormatDateTime

See also	Example

Formats a TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::AnsiString __fastcall FormatDateTime(const System::AnsiString Format, System::TDateTime DateTime);

Description

FormatDateTime formats the TDateTime object given by DateTime using the format given by Format. The following format specifiers are supported:

Specifier	Displays
c	Displays the date using the format given by the ShortDateFormat global variable, followed by the time using the format given by the LongTimeFormat global variable. The time is not displayed if the fractional part of the DateTime value is zero.
d	Displays the day as a number without a leading zero (1-31).
dd	Displays the day as a number with a leading zero (01-31).
ddd	Displays the day as an abbreviation (Sun-Sat) using the strings given by the ShortDayNames global variable.
dddd	Displays the day as a full name (Sunday-Saturday) using the strings given by the LongDayNames global variable.
ddddd	Displays the date using the format given by the ShortDateFormat global variable.
dddddd	Displays the date using the format given by the LongDateFormat global variable.
m	Displays the month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.
mm	Displays the month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.
mmm	Displays the month as an abbreviation (Jan-Dec) using the strings given by the ShortMonthNames global variable.
mmmm	Displays the month as a full name (January-December) using the strings given by the LongMonthNames global variable.
yy	Displays the year as a two-digit number (00-99).
yyyy	Displays the year as a four-digit number (0000-9999).
h	Displays the hour without a leading zero (0-23).
hh	Displays the hour with a leading zero (00-23).
n	Displays the minute without a leading zero (0-59).
nn	Displays the minute with a leading zero (00-59).
s	Displays the second without a leading zero (0-59).
ss	Displays the second with a leading zero (00-59).
t	Displays the time using the format given by the ShortTimeFormat global variable.
tt	Displays the time using the format given by the LongTimeFormat global variable.
am/pm	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon, and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly.
a/p	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.
ampm	Uses the 12-hour clock for the preceding h or hh specifier, and displays the contents of the TimeAMString global variable for any hour before noon, and the contents of the TimePMString global variable for any hour after noon.
/	Displays the date separator character given by the DateSeparator global variable.
:	Displays the time separator character given by the TimeSeparator global variable.
'xx'/"xx"	Characters enclosed in single or double quotes are displayed as-is, and do not affect formatting.
Format specifiers may be written in upper case as well as in lower case letters--both produce the same result.

If the AnsiString given by the Format parameter is empty, the TDateTime object is formatted as if a 'c' format specifier had been given.


FormatFloat

See also	Example

Formats a floating point value.

Unit

SysUtils

Category

Floating point conversion routines

extern PACKAGE System::AnsiString __fastcall FormatFloat(const System::AnsiString Format, Extended Value);

Description

FormatFloat formats the floating-point value given by Value using the format string given by Format. The following format specifiers are supported in the format string:

Specifier	Represents
0	Digit place holder. If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the output string. Otherwise, a '0' is stored in that position in the output string.
#	Digit placeholder. If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
.	Decimal point. The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored. The actual character used as a the decimal separator in the output string is determined by the DecimalSeparator global variable. The default value of DecimalSeparator is specified in the Number Format of the International section in the Windows Control Panel.
,	Thousand separator. If the format string contains one or more ',' characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of ',' characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is determined by the ThousandSeparator global variable. The default value of ThousandSeparator is specified in the Number Format of the International section in the Windows Control Panel.
E+	Scientific notation. If any of the strings 'E+', 'E-', 'e+', or 'e-' are contained in the format string, the number is formatted using scientific notation. A group of up to four '0' characters can immediately follow the 'E+', 'E-', 'e+', or 'e-' to determine the minimum number of digits in the exponent. The 'E+' and 'e+' formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The 'E-' and 'e-' formats output a sign character only for negative exponents.
'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting.
;	Separates sections for positive, negative, and zero numbers in the format string.
The locations of the leftmost '0' before the decimal point in the format string and the rightmost '0' after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ('0' or '#') to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the '.' character in the format string, the extra digits are output before the first digit placeholder.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

One section: The format string applies to all values.

Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

If the section for positive values is empty, or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits, corresponding to a call to FloatToStrF with the ffGeneral format. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.


FormatMaskText

See also

Returns an AnsiString formatted using an edit mask.

Unit

Mask

Category

miscellaneous routines

extern PACKAGE System::AnsiString __fastcall FormatMaskText(const System::AnsiString EditMask, const System::AnsiString Value);

Description

Call FormatMaskText to apply the mask specifed by the EditMask parameter to the text AnsiString specified by the Value parameter. The edit mask AnsiString consists of three fields with semicolons separating them. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of the mask are matched to characters in the Value parameter or are inserted into the Value AnsiString. The third part of the mask is the character used to represent missing characters in the mask.

These are the special characters used in the first field of the mask:

Character	Meaning in mask
!	If a ! character appears in the mask, optional characters are represented in the returned string as leading blanks. If a ! character is not present, optional characters are represented in the returned string as trailing blanks.
>	If a > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a < character is encountered.
<	If a < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a > character is encountered.
<>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case present in the Value parameter.
\	The character that follows a \ character is a literal character. Use this character to use any of the mask special characters as a literal.
L	The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.
l	The l character permits only an alphabetic character in this position, but doesn't require it.
A	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.
a	The a character permits an alphanumeric character in this position, but doesn't require it.
C	The C character requires an arbitrary character in this position.
c	The c character permits an arbitrary character in this position, but doesn't require it.
0	The 0 character requires a numeric character only in this position.
9	The 9 character permits a numeric character in this position, but doesn't require it.
#	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.
:	The : character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel, that character is substituted in the returned string.
/	The / character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the regional settings of the Control Panel, that character is substituted in the returned string.
;	The ; character is used to separate the three fields of the mask.
_	The _ character automatically inserts spaces into the returned string.
Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters are inserted automatically if the second field of the mask is 0, or matched to characters in the Value parameter if the second field is any other value. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask are included in the Value parameter. For example, the mask for a telephone number with area code could be the following string:

(000)_000-0000;0;*

The 0 in the second field indicates that the Value parameter should consist of the 10 digits of the phone number, rather than the 14 characters that make up the final formatted string.

A 0 in the second field indicates that literals are inserted into the Value string, any other character indicates that they should be included. The character to indicate whether literals should be included can be changed by changing the MaskNoSave typed constant that is declared in the Mask unit.

The third field of the mask is the character that appears in the returned string for blanks (characters that do not appear in Value). By default, this is the same as the character that stands for literal spaces. The two characters appear the same in the returned string.

Note:	When working with multibyte character sets, such as Japanese shift-JIS, each special mask character represents a single byte. To specify double-byte characters using the L,l,A,a,C, or c specifiers, the mask characters must be doubled as well. For example, LL would represent two single-byte alphabetic characters or a one double-byte character. Only single-byte literal characters are supported.


FPower10

Multiplies a value by a specified power of 10.

Unit

System

Category

arithmetic routines

extern PACKAGE void __fastcall FPower10(void);

Description

FPower10 returns Val * 10**Pow. It is more efficient to call FPower10 than to perform the same computation explicitly.


Frame3D procedure
Frame3D

See also

Draws a three dimensional frame on a canvas.

Unit

extctrls

Category

graphics utilities

extern PACKAGE void __fastcall Frame3D(Graphics::TCanvas * Canvas, Windows::TRect &Rect, Graphics::TColor TopColor, Graphics::TColor BottomColor, int Width);

Description

Use Frame3D to create three-dimensional effects when drawing directly on a canvas.  The Canvas parameter is the canvas to draw on.  The Rect parameter specifies the position where the three-dimensional canvas should appear.  The TopColor and BottomColor parameters indicate the colors that appear on the left and top or the right and bottom of the rectangle respectively.  The Width parameter specifies the width of the frame.

To create a raised effect, the TopColor should be a light color and the BottomColor should be a shadow color.  To create a depressed effect, the TopColor should be the shadow color and the BottomColor should be the light color.  To create a beveled effect, draw a frame immediately inside another frame with the colors reversed.


Frexp procedure
Frexp

Separates the Mantissa and Exponent of X

Unit

Math

Category

arithmetic routines

extern PACKAGE void __fastcall Frexp(Extended X, Extended &Mantissa, int &Exponent);

Description

Frexp separates the Mantissa and Exponent of X.


FutureValue

See also

Calculates the future value of an investment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall FutureValue(Extended Rate, int NPeriods, Extended Payment, Extended PresentValue, TPaymentTime PaymentTime);

Description

FutureValue returns the future value of an investment of PresentValue where Payment is invested for NPeriods at the rate of Rate per period. The PaymentTime parameter indicates whether the investment is an ordinary annuity or an annuity due (enter 0 if payments are at the end of each period, 1 if they are at the beginning).


GetActiveOleObject

See also

Retrieves a reference to an IDispatch interface to a currently running, registered OLE object.

Unit

ComObj

Category

COM utilities

extern PACKAGE _di_IDispatch __fastcall GetActiveOleObject(const System::AnsiString ClassName);

Description

GetActiveOleObject returns a reference to a the IDispatch interface of the active object for the given class indicated by ClassName. ClassName is the programmatic ID for the class of the active object from the OLE running object table. GetActiveOleObject is used to access the OLE running object table. To add an object to this table, use the RegisterActiveObject API.

If either the the class object or the IDispatch interface are not successfully returned, an EOleSysError exception is thrown.


GetCaptureControl

See also

Returns the control, if any, that currently recieves all mouse messages.

Unit

Controls

Category

mouse handling utilities

extern PACKAGE TControl * __fastcall GetCaptureControl(void);

Description

Call GetCaptureControl to determine which control is currently processing mouse messages.  When a control has captured the mouse, it receives all mouse messages, even if the mouse is not over the control.


GetCharSetValues procedure
GetCharSetValues

See also 	Example

Passes the name of every predefined character set string to a callback function.

Unit

Graphics

Category

graphics utilities

extern PACKAGE void __fastcall GetCharsetValues(Classes::TGetStrProc &Proc);

Description

Call GetCharsetValues to execute a callback for every character set name that has a corresponding constant in C++Builder programs that use the VCL.  The Proc parameter is the callback function that is called for every character set constant name.

Note:	To convert the strings that are passed to the callback into the TFontCharset type, use the IdentToCharset function.


GetClass

See also	Example

Returns a registered persistent class given its class name.

Unit

Classes

Category

class handling routines

extern PACKAGE System::TMetaClass* __fastcall GetClass(const System::AnsiString ClassName);

Description

Call GetClass to obtain a class from a class name. This class can be used as a parameter to routines that require a class.

The Class must be registered before GetClass can find it.  Form classes and component classes that are referenced in a form declaration (instance variables) are automatically registered when the form is loaded.  Other classes can be registered by calling RegisterClass or RegisterClasses.

To obtain an unregistered class from a class name, use the __classid routine.


GetColorValues procedure
GetColorValues

See also

Passes the name of every predefined color constant to a callback function.

Unit

Graphics

Category

graphics utilities

extern PACKAGE void __fastcall GetColorValues(Classes::TGetStrProc &Proc);

Description

Call GetColorValues to execute a callback for every TColor constant in C++Builder applications that use the VCL.  The Proc parameter is the callback function that is called for color constant name.

Note:	To convert the strings that are passed to the callback into the TColor type, use the IdentToColor function.


GetComCtlVersion

See also

Indicates which version of ComCtl32.dll is installed.

Unit

ComCtrls

Category

Windows controls utilities

extern PACKAGE int __fastcall GetComCtlVersion(void);

Description

The appearance and behavior of some common controls, such as tool bars and cool bars, varies depending on which version of ComCtl32.dll is installed. Use GetComCtlVersion to determine which version is installed.  GetComCtlVersion returns an integer that includes the major version number as the high-order WORD and the minor version number as the low-order word.

Installing Microsoft’s Internet Explorer on a system affects which version of ComCtl32.dll is installed. To help determine which version of Internet Explorer is installed, the ComCtrls unit defines two constants:

Constant	Value	Meaning

ComCtlVersionIE3	$00040046	The version of ComCtl32.dll installed with Internet Explorer version 3.

ComCtlVersionIE$	$00040047	The version of ComCtl32.dll installed with Internet Explorer version 4.

To quickly determine which version of Internet Explorer is installed, you can compare the return value of GetComCtlVersion with one of these constants.


GetCurrentDir

See also

Returns the name of the current directory.

Unit

SysUtils

Category

file management routines

extern PACKAGE System::AnsiString __fastcall GetCurrentDir();

Description

GetCurrentDir returns an AnsiString containing the name of the current directory.


GetCursorValues procedure
GetCursorValues

See also

Passes the name of every predefined cursor constant to a callback.

Unit

controls

Category

cursor management routines

extern PACKAGE void __fastcall GetCursorValues(Classes::TGetStrProc &Proc);

Description

Call GetCursorValues to execute a callback for every built-in cursor constant in C++Builder applications that use the VCL.  The Proc parameter is the callback function that is called for every cursor constant name.

Note:	To convert the strings that are passed to the callback into actual cursors, use IdentToCursor.  To convert a cursor into a constant name that can be compared with the string passed to the callback, use CursorToIdent.


GetDefFontCharset

See also

Returns the character set of the default system font.

Unit

Graphics

Category

graphics utilities

extern PACKAGE TFontCharset __fastcall GetDefFontCharSet(void);

Description

Call GetDefFontCharset to determine the character set that is used when a font is not explicitly assigned to a control.  This character set can be used to initialize a font that is specified by font name only, to best match the characters for the locale of the machine on which the application is running.


GetDIB

See also

Returns the info header and image for a device independant bitmap.

Unit

Graphics

Category

graphics utilities

extern PACKAGE bool __fastcall GetDIB(HBITMAP Bitmap, HPALETTE Palette, void *BitmapInfo, void *Bits);

Description

Call GetDIB to convert a device dependant bitamp into a device independant bitmap (DIB).  Pass the handle to a device dependant bitmap and a handle to its palette as the Bitmap and Palette parameters.  GetDIB fills in the BitmapInfo and Bits parameters with the info header and image of the corresponding DIB.  GetDIB returns true if the bitmap was succesfully converted into a DIB, false otherwise.

Before calling GetDIB, the memory for the info header and image must be allocated.  Call GetDIBSizes to determine the amount of memory that must be allocated for the info header and image.


GetDIBSizes procedure
GetDIBSizes

See also

Returns the size of the info header and of the image for a device independant bitmap.

Unit

Graphics

Category

graphics utilities

extern PACKAGE void __fastcall GetDIBSizes(HBITMAP Bitmap, int &InfoHeaderSize, int &ImageSize);

Description

Call GetDIBSizes to determine the amount of memory needed to convert a device dependant bitamp into a device independant bitmap (DIB).  Pass the handle to a device dependant bitmap as the Bitmap parameter.  GetDIBSizes returns the sizes of the info header and image of the corresponding DIB as the InfoHeaderSize parameter and the ImageSize parameter, respectively.

Call GetDIBSizes to determine the amount of memory that must be allocated before calling GetDIB to convert a device dependant bitmap into a device independant bitmap.


GetExtensionVersion

See also

Returns the name and version number of an ISAPI or NSAPI application.

Unit

ISAPIApp

Category

HTTP utilities

BOOL __fastcall GetExtensionVersion(Isapi2::THSE_VERSION_INFO &Ver);

Description

Do not call GetExtensionVersion. GetExtension is exported by ISAPI and NSAPI DLLs. It provides an entry point that is called by ISAPI or NSAPI web servers to obtain version information about the web server application.


GetFormatSettings procedure
GetFormatSettings

Resets the date and number format parameters to default values.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE void __fastcall GetFormatSettings(void);

Description

GetFormatSettings resets all date and number format variables to their default values. GetFormatSettings is called in non-console C++Builder applications in response to WM_WININICHANGE messages.


GetHeapStatus

Returns the current status of the memory manager.

Unit

System or ShareMem

Category

memory management routines

extern "C" System::THeapStatus __fastcall GetHeapStatus(void);

Description

GetHeapStatus returns the current status of the memory manager in a THeapStatus record. Include the System unit to obtain information about the global heap. Include the ShareMem unit instead if the memory is shared between different processes.

These are the meanings of the values in the THeapStatus record:.

Field	Meaning
TotalAddrSpace	The (current) total address space available to your program, in bytes. This will grow as your program's dynamic memory usage grows.
TotalUncommitted	The total number of bytes (of TotalAddrSpace) for which space has not been allocated in the swap file.
TotalCommitted	The total number of bytes (of TotalAddrSpace) for which space has been allocated in the swap file.Note: TotalUncommitted + TotalCommitted = TotalAddrSpace
TotalAllocated	The total number of bytes dynamically allocated by your program.
TotalFree	The total number of free bytes available in the (current) address space for allocation by your program. If this number is exceeded, and enough virtual memory is available, more address space will be allocated from the OS; TotalAddrSpace will be incremented accordingly.
FreeSmall	Total bytes of small memory blocks which are not currently allocated by your program.
FreeBig	Total bytes of big memory blocks which are not currently allocated by your program. Large free blocks can be created by coalescing smaller, contiguous, free blocks or by freeing a large dynamic allocation.  (The exact size of the blocks is immaterial)
Unused	Total bytes which have never been allocated by your program. Note: Unused + FreeBig + FreeSmall = TotalFree Note: These three are speaking about dynamic allocation from the user program.
Overhead	The total number of bytes required by the heap manager to manage all the blocks dynmically allocated by your program.
HeapErrorCode	Indicates the current status of the heap, as internally determined.
Note:	TotalAddrSpace, TotalUncommitted and TotalCommitted refer to OS memory used by the program, where as TotalAllocated and TotalFree refer to the heap memory used within the program by dynamic allocations. Therefore, to monitor dynamic memory used in your program use TotalAllocated and TotalFree.


GetLongHint

See also	Example

Returns the second part of a two-part hint AnsiString.

Unit

Controls

Category

Help Hint routines

extern PACKAGE System::AnsiString __fastcall GetLongHint(const System::AnsiString Hint);

Description

Call GetLongHint to obtain the long version of the hint specified as the value of a Hint property. The second part of the hint is the text following the | character. If the Hint AnsiString value is not separated into two parts, GetLongHint returns the entire AnsiString.


GetMemoryManager procedure
GetMemoryManager

See also 	Example

Returns the entry points of the currently installed memory manager.

Unit

System

Category

memory management routines

extern PACKAGE void __fastcall GetMemoryManager(TMemoryManager &MemMgr);

Description

GetMemoryManager returns the entry points of the currently installed memory manager in a TMemoryManager record.


GetOleFont procedure
GetOleFont

See also

Creates an OLE font object that is directly mapped to a native VCL TFont.

Unit

AXCtrls

Category

COM utilities

virtual void __fastcall GetOleFont(_di_IFontDisp &OleFont) = 0;

Description

OLE conventions implement fonts as automation objects that contain the properties of the font.  This routine creates an adapter object that maps the properties of a native VCL TFont into an OLE font object, thereby allowing an OLE client to access the font properties of a VCL control. Call this function when you implement a method that retrieves a TFont value from a VCL object and returns it as an OLE font.

The Font parameter is a pointer to the native TFont. This can be the Font property of a VCL control.  The OLE font is returned in the OleFont parameter. The resulting OLE font object is a direct connection to the native VCL font, so changing the OLE font's properties will change the TFont's properties, and vice-versa.


GetOlePicture procedure
GetOlePicture

See also

Creates an OLE picture object that is directly mapped to a native VCL TPicture.

Unit

AXCtrls

Category

COM utilities

virtual void __fastcall GetOlePicture(_di_IPictureDisp &OlePicture) = 0;

Description

OLE conventions implement fonts as automation objects that contain the properties of the picture.  This routine creates an adapter object that maps the properties of a native VCL TPicture into an OLE picture object, thereby allowing an OLE client to access the picture properties of a VCL control. Call this function when you implement a method that retrieves a TPicture value from a VCL object and returns it as an OLE picture.

The Picture parameter is a pointer to the native TPicture. This can be the Font property of a VCL control.  The OLE picture is returned in the OlePicture parameter. The resulting OLE picture object is a direct connection to the native VCL picture, so changing the OLE picture's properties will change the TPicture's properties, and vice-versa.


GetPackageDescription

See also

Returns the description resource from a package.

Unit

SysUtils

Category

package support routines

extern PACKAGE System::AnsiString __fastcall GetPackageDescription(char * ModuleName);

Description

Call GetPackageDescription to obtain the description stored with the named package. If the package does not have a description resource, GetPackageDescription returns an empty AnsiString.


GetPackageInfo procedure
GetPackageInfo

See also

Enumerates all the units and required packages for a package.

Unit

SysUtils

Category

package support routines

extern PACKAGE void __fastcall GetPackageInfo(Windows::HINST Module, void * Param, int &Flags, TPackageInfoProc InfoProc);

Description

Call GetPackageInfo to process the information in a package's information table. The InfoProc callback is called for every unit included in the package and for every package required by the package. Module is the module handle for the package. GetPackageInfo passes any application-supplied information passed in the Param parameter to the InfoProc callback. The package's information flags are passed to the InfoProc and returned in the Flags parameter.


GetParentForm

See also

Returns the form or property page that contains a specified control.

Unit

Forms

Category

Windows controls utilities

extern PACKAGE TCustomForm* __fastcall GetParentForm(Controls::TControl* Control);

Description

Call GetParentForm to obtain the descendant of TCustomForm that contains the control specified by the Control parameter. If the control is not contained in a VCL form (for example, an ActiveX control embedded in another type of window), GetParentFrom returns NULL.


GetShortHint

See also	Example

Returns the first part of a two-part hint AnsiString.

Unit

Controls

Category

Help Hint routines

extern PACKAGE System::AnsiString __fastcall GetShortHint(const System::AnsiString Hint);

Description

Call GetShortHint to obtain the short version of the hint specified as the value of a Hint property. The first part of the hint is the text preceding the | character. If the Hint AnsiString value is not separated into two parts, GetShortHint returns the entire AnsiString.


GradToRad

See also

Converts grad measurements to radians.

Unit

Math

Category

measurement conversion routines

extern PACKAGE Extended __fastcall GradToRad(Extended Grads);

Description

GradToRad converts angles of grad measure into radians, where

radians = grads(pi/200).


GraphicExtension

See also	Example

Returns the default file-name extension of a graphics object.

Unit

Graphics

Category

graphics utilities

extern PACKAGE System::AnsiString __fastcall GraphicExtension(System::TMetaClass* GraphicClass);

Description

Call GraphicExtension to obtain a default extension value for the DefaultExt property of a Save Picture dialog. GraphicExtension returns the default extension for the type of graphics object specified by the GraphicClass parameter. The TGraphicClass type is the class type for descendants TGraphic.

These are the file extensions returned for each built-in graphics class:

Graphic class	File extension returned
TBitmap	bmp
TIcon	ico
TMetafile	emf
If custom graphics classes register a file extension, GraphicExtension will return that extension when passed the custom graphics class as an argument.


GraphicFileMask

See also

Returns a mask AnsiString that specifies the valid extensions for a graphic class.

Unit

Graphics

Category

graphics utilities

extern PACKAGE System::AnsiString __fastcall GraphicFileMask(System::TMetaClass* GraphicClass);

Description

Call GraphicFileMask to obtain a mask to determine the file extensions associated with a graphic class. The GraphicClass parameter can be one of these values: TBitmap, TGraphic, TIcon, TMetafile, or a user-defined descendant of TGraphic. These are the strings that are returned for each built-in graphics class:

Graphic class	Filter string returned
TBitmap	*.bmp
TIcon	*.ico
TMetafile	*.emf;*.wmf
TGraphic	*.bmp;*.ico;*.emf;*.wmf


GraphicFilter

See also	Example

Returns a filter AnsiString compatible with the Filter property of an Open or Save dialog.

Unit

Graphics

Category

graphics utilities

extern PACKAGE System::AnsiString __fastcall GraphicFilter(System::TMetaClass* GraphicClass);

Description

Call GraphicFilter to obtain a value for the Filter property of an Open Picture or Save Picture dialog box. The GraphicClass parameter can be one of these values: TBitmap, TGraphic, TIcon, TMetafile,  or a user-defined descendant of TGraphic. These are the strings that are returned for each built-in graphics class:

Graphic class	Filter string returned
TBitmap	Bitmaps (*.bmp)|*.bmp
TIcon	Icons (*.ico)|*.ico
TMetafile	All(*.emf;*.wmf)|*.emf;*.wmf|Enhanced Metafiles (*.emf)|*.emf|Metafiles(*.wmf)|*.wmf
TGraphic	All (*.bmp;*.ico;*.emf;*.wmf)|*.bmp;*.ico;*.emf; *.wmf|Bitmaps (*.bmp)|*.bmp|Icons (*.ico)|*.ico|Enhanced Metafiles (*.emf)|*.emf|Metafiles(*.wmf)|*.wmf


GUIDToString

See also

Converts a class identifier GUID to an AnsiString.

Unit

ComObj

Category

COM utilities

extern PACKAGE System::AnsiString __fastcall GUIDToString(const GUID &ClassID);

Description

GUIDToString converts a GUID into an AnsiString of printable characters. Each GUID will always convert to a unique AnsiString.

If GUIDToString succeeds it returns an AnsiString to the requested GUID. If GUIDToString fails an EOleSysError exception is thrown with an error code indicating the cause of the error.


HtmlTable

See also

Generates the HTML image of a dataset, using the properties and events of a table producer object.

Unit

DBWeb

Category

miscellaneous routines

extern PACKAGE System::AnsiString __fastcall HtmlTable(Db::TDataSet* DataSet, TDSTableProducer* DataSetHandler, int MaxRows);

Description

Call HtmlTable to obtain a sequence of HTML commands that describe a dataset in tabular format. The DataSet parameter indicates the dataset whose records are converted into an HTML image. The DataSetHandler parameter is the table producer whose properties describe the attributes of the resulting image, and whose event handlers respond to events that occur during the generation of the image. The MaxRows parameter is the maximum number of records from the dataset that will appear in the image.

Calling HtmlTable is equivalent to calling the Content method of the DataSetHandler parameter after setting its DataSet and MaxRows properties to the values given for the parameters of the same names.


HTTPExtensionProc

See also

Receives an HTTP request message for an ISAPI or NSAPI application.

Unit

ISAPIApp

Category

HTTP utilities

int __fastcall HttpExtensionProc(Isapi2::TEXTENSION_CONTROL_BLOCK &ECB);

Description

Do not call HttpExtensionProc. HttpExtensionProc is exported by ISAPI and NSAPI DLLs. It provides an entry point that is called by ISAPI or NSAPI web servers when they receive HTTP request messages.


Hypot

Calculates the length of the hypotenuse.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall Hypot(Extended X, Extended Y);

Description

Hypot returns the length of the hypotenuse of a triangle. Specify the lengths of the sides adjacent to the right angle in X and Y.  Hypot uses the formula

Sqrt(X**2 + Y**2)


IdentToCharset

See also

Translates the name of a character set constant to the corresponding character set.

Unit

Graphics

Category

graphics utilities

extern PACKAGE bool __fastcall IdentToCharset(const System::AnsiString Ident, int &Charset);

Description

Call IdentToCharset to reverse the translation performed by CharSetToIdent. This method is useful for converting the strings generated by GetCharsetValues into useable character sets.  IdentToCharset returns true if the Ident parameter is successfully converted into a character set that is returned by the Charset parameter.  IdentToCharset returns false if the Ident parameter is not the name of one of the C++Builder VCL character set constants.


IdentToColor

See also

Translates the name of a color constant to the corresponding TColor value.

Unit

Graphics

Category

graphics utilities

extern PACKAGE bool __fastcall IdentToColor(const System::AnsiString Ident, int &Color);

Description

Call IdentToColor to reverse the translation performed by ColorToIdent. This method is useful for converting the strings generated by GetColorValues into useable TColor values.  IdentToColor returns true if the Ident parameter is successfully converted into a color that is returned by the Color parameter.  IdentToColor returns false if the Ident parameter is not the name of one of the C++Builder VCL color constants.

Note:	If the string identifier for a color may represent either a hex value or a color constant, use the StringToColor function instead.


IdentToCursor

See also

Translates a predefined cursor constant into a cursor.

Unit

controls

Category

cursor management routines

extern PACKAGE bool __fastcall IdentToCursor(const System::AnsiString Ident, int &Cursor);

Description

Call IdentToCursor to reverse the translation performed by the CursorToIdent function. This method is useful for converting the strings generated by GetCursorValues into useable cursors.  IdentToCursor returns true if the Ident parameter is successfully converted into a cursor.  IdentToCursor returns false if the Ident parameter is not the name of one of the C++Builder built-in cursor constants.

Note:	If the string identifier for a cursor may represent either a numeric value or a cursor constant, use the StringToCursor function instead.


IncMonth

See also

Returns a date shifted by a specified number of months.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall IncMonth(const System::TDateTime Date, int NumberOfMonths);

Description

IncMonth returns the value of the Date parameter, incremented by  NumberOfMonths months.  NumberOfMonths can be negative, to return a date N months previous.

If the input day of month is greater than the last day of the resulting  month, the day is set to the last day of the resulting month.  The time of day specified by the Date parameter is copied to the  result.


InputBox

See also 	Example

Displays an input dialog box that enables the user to enter a string.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE System::AnsiString __fastcall InputBox(const System::AnsiString ACaption, const System::AnsiString APrompt, const System::AnsiString ADefault);

Description

Call InputBox to bring up an input dialog box ready for the user to enter a string in its edit box. The ACaption parameter is the caption of the dialog box, the APrompt parameter is the text that prompts the user to enter input in the edit box, and the ADefault parameter is the string that appears in the edit box when the dialog box first appears.

If the user chooses the Cancel button, InputBox returns the default string. If the user chooses the OK button, InputBox returns the string in the edit box.

Use the InputBox function when there is a default value that should be used when the user chooses the Cancel button (or presses Esc) to exit the dialog. If the application needs to know whether the user chooses OK or Cancel , use the InputQuery function.


InputQuery

See also 	Example

Displays an input dialog that enables the user to enter a string.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE bool __fastcall InputQuery(const System::AnsiString ACaption, const System::AnsiString APrompt, System::AnsiString &Value);

Description

Call InputQuery to bring up an input dialog box ready for the user to enter a string in its edit box. The ACaption parameter is the caption of the dialog box, the APrompt parameter is the text that prompts the user to enter input in the edit box, and the Value parameter is the string that appears in the edit box when the dialog box first appears.

If the user enters a string in the edit box and chooses OK, the Value parameter changes to the new value.

InputQuery returns true if the user chooses OK, and false if the user chooses Cancel or presses the Esc key.

If the default value should be used when the user cancels out of the dialog, use InputBox.


InterestPayment

See also

Calculates the interest portion of a loan payment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall InterestPayment(Extended Rate, int Period, int NPeriods, Extended PresentValue, Extended FutureValue, TPaymentTime PaymentTime);

Description

Rate represents the fixed periodic interest rate, Period identifies the payment period, NPeriods is the number of periods of the loan, PresentValue represents the amount borrowed (the principal), FutureValue is the future value of the investment, and PaymentTime indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1 or 0, respectively).


InterestRate

See also

Returns the interest rate required to increase PresentValue to FutureValue.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall InterestRate(int NPeriods, Extended Payment, Extended PresentValue, Extended FutureValue, TPaymentTime PaymentTime);

Description

InterestRate calculates the interest rate required in order for an investment of PresentValue, with periodic payments of Payment, to be worth FutureValue within NPeriods compounding periods. If NPeriods represents years, an annual interest rate results; if NPeriods represents months, a monthly interest rate results, and so on. The PaymentTime parameter indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1or 0, respectively).


InternalRateOfReturn

See also

Calculates the internal rate of return for an investment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall InternalRateOfReturn(Extended Guess, const double * CashFlows, const int CashFlows_Size);

Description

InternalRateOfReturn determines the internal rate of return on an investment. It references an array that contains cash flow information and uses the supplied internal rate of return estimate to calculate results.

Before using this function, define an array containing expected cash flow amounts over a period of time. It is assumed that the amounts are received at regular intervals. Negative amounts are interpreted as cash outflows, and positive amounts as inflows. The first amount must be a negative number, to reflect the initial investment. The following amounts can all be the same for each time period, or they can be different (including a mixture of negatives, positives, or zeros).


IntPower

Calculates Base to an integral power.

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall IntPower(Extended Base, int Exponent);

Description

IntPower raises Base to the power specified by Exponent.


IntToHex

See also 	Example

Returns the hex representation of an integer.

Unit

SysUtils

Category

numeric formatting routines

extern PACKAGE System::AnsiString __fastcall IntToHex(int Value, int Digits);

Description

IntToHex converts a number into a string containing the number's hexadecimal (base 16) representation. Value is the number to convert. Digits indicates the minimum number of hexadecimal digits to return.


IntToStr

See also 	Example

Converts an integer to an AnsiString.

Unit

SysUtils

Category

numeric formatting routines

extern PACKAGE System::AnsiString __fastcall IntToStr(int Value);

Description

IntToStr converts an integer into an AnsiString containing the decimal representation of that number.


IsAccel

See also

Indicates whether a particular character is an accelerator character (or hot key) within a given menu caption or other text string.

Unit

Forms

Category

miscellaneous routines

extern PACKAGE bool __fastcall IsAccel(Word VK, const System::AnsiString Str);

Description

Call IsAccel to determine whether the character represented by the VK parameter appears in the AnsiString represented by the Str parameter as an accelerator.  IsAccel only looks for accelerators that are identified by a preceding ampersand (&).  Such accelerators appear underlined in the string when displayed as a control’s caption.

Use IsAccel when processing key events to determine whether a key matches an accelerator character in a control’s caption.

Note:	IsAccel does not recognize hot key combinations in menu items that are identified by the HotKey property.


IsDelimiter

See also

Indicates whether a specified character in a string matches one of a set of delimiters.

Unit

SysUtils

Category

string handling routines

extern PACKAGE bool __fastcall IsDelimiter(const System::AnsiString Delimiters, const System::AnsiString S, int Index);

Description

Call IsDelimiter to determine whether the character at byte offset Index in the AnsiString S is one of the delimiters in the AnsiString Delimiters. Index is the 0-based index of the byte in question, where 0 is the first byte of the AnsiString, 1 is the second byte, and so on.

When working with a multi-byte character system (MBCS), IsDelimiter checks to make sure the indicated byte is not part of a double byte character. The delimiters in the Delimeters parameter must all be single byte characters.


IsDragObject

See also

Indicates whether a specified object is a TDragObject descendant.

Unit

Controls

Category

drag and drop routines

extern PACKAGE bool __fastcall IsDragObject(System::TObject * Sender);

Description

Use IsDragObject to determine whether the object being dragged in a drag-and-drop operation is a specialized TDragObject that represents the dragged control’s data rather then the control itself.  Use IsDragObject on the Source parameter in an OnDragOver event handler to determine the type of object being dragged and whether it should be accepted.  Use IsDragObject on the Source parameter of an OnDragDrop event handler to determine how to interpret the dragged object’s data.


IsLeapYear

See also 	Example

Indicates whether a specified year is a leap year.

Unit

SysUtils

Category

date/time routines

extern PACKAGE bool __fastcall IsLeapYear(Word Year);

Description

Call IsLeapYear to determine whether the year specified by the Year parameter is a leap year.  Year specifies the calandar year.

Use DecodeDate to obtain the value of  Year for IsLeapYear from a TDateTime object.


IsPathDelimiter

See also

Indicates whether the byte at position Index of an AnsiString is the backslash character.

Unit

SysUtils

Category

string handling routines

extern PACKAGE bool __fastcall IsPathDelimiter(const System::AnsiString S, int Index);

Description

Call IsPathDelimiter to determine whether a position in the AnsiString S contains the backslash path delimiter (\). The Index parameter specifies the postion of the character in question, where 0 is the first byte, 1 is the second byte, and so on.

When working with a multi-byte character system (MBCS), IsPathDelimiter distinguishes between a true backslash character, and the byte of the same value that can appear as the second byte of a double byte character.

To test for more characters than just the backslash character, use IsDelimiter.


IsValidIdent

Tests for a valid Pascal identifier.

Unit

SysUtils

Category

miscellaneous routines

extern PACKAGE bool __fastcall IsValidIdent(const System::AnsiString Ident);

Description

IsValidIdent returns true if the given AnsiString is a valid identifier. An identifier is defined as a character from the set ['A'..'Z', 'a'..'z', '_'] followed by zero or more characters from the set ['A'..'Z', 'a'..'z', '0..'9', '_'].


LastDelimiter

See also

Returns the byte index in S of the last character that matches any character in the Delimiters AnsiString.

Unit

SysUtils

Category

string handling routines

extern PACKAGE int __fastcall LastDelimiter(const System::AnsiString Delimiters, const System::AnsiString S);

Description

Call LastDelimiter to locate the last delimiter in the AnsiString S. When working with multi-byte character sets (MBCS), the AnsiString S may contain double byte characters, but the delimiters listed in the Delimeters paramter must all be single byte non-null characters.

For example, the line

MyIndex = LastDelimiter("\\.:","c:\\filename.ext");

sets MyIndex to 12.


Ldexp

Calculates X * (2**P)

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall Ldexp(Extended X, int P);

Description

Ldexp returns X times (2 to the power of P).


LineStart

Finds the end of the last whole line in a buffer.

Unit

classes

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall LineStart(char * Buffer, char * BufPos);

Description

Use LineStart to find the start of the last partial line in the buffer. LineStart starts at BufPos and scans backwards for a line-feed character (\n).  It returns a pointer to that character.  If no line-feed char is found, it returns the Buffer pointer.  Buffer should point to the begining of a block of memory and BufPos to the end of the block you want to scan.

Note:	The TParser class uses LineStart to locate line-endings in chunks of text read into a fixed-sized buffer.  When the last full line of text is parsed, the parser moves the last partial line of text from the end of the buffer to the front and fills the rest of the buffer with new data from disk.


LnXP1

Returns the natural log of (X+1)

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall LnXP1(Extended X);

Description

LnXP1 returns the natural logarithm of (X+1).  Use LnXP1 when X is a value near 0.


LoadPackage

See also

Loads a specified package.

Unit

SysUtils

Category

package support routines

extern PACKAGE Windows::HINST __fastcall LoadPackage(const System::AnsiString Name);

Description

LoadPackage loads the package specified by the Name parameter, checks for duplicate units, and calls the initialization blocks of all units contained in the package.


LoadStr

Loads a string from the application's executable file.

Unit

SysUtils

Category

miscellaneous routines

extern PACKAGE System::AnsiString __fastcall LoadStr(int Ident);

Description

LoadStr loads the string resource given by Ident from the application's executable file. If the string resource does not exist, an empty AnsiString is returned.

Moving display strings into string resources makes an application easier to localize without rewriting the program.


Log2

See also

Calculates log base 2.

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall Log2(Extended X);

Description

Log2 returns the log base 2 of X.


Log10

See also

Calculates log base 10.

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall Log10(Extended X);

Description

Log10 returns the log base 10 of X.


LoginDialog

See also

Brings up the database Login dialog to allow the user to connect to a database server.

Unit

DBLogDlg

Category

dialog and message routines

extern PACKAGE bool __fastcall LoginDialog(const System::AnsiString ADatabaseName, System::AnsiString &AUserName, System::AnsiString &APassword);

Description

Call LoginDialog to bring up the standard Login dialog box to prompt the user for a valid user name and password. The ADatabaseName parameter specifies the database for which access is being requested. It corresponds to the DatabaseName property of the TDatabase object. The dialog returns the user name and password as the AUserName and APassword parameters.

LoginDialog returns false if the user cancels out of the dialog. If LoginDialog returns true, the application can attempt to connect to the database server using the supplied user name and password.

Note:	If the user should not be permitted to change the user name from within the login dialog, use the LoginDialogEx function.


LoginDialogEx

See also

Brings up the database Login dialog to allow the user to connect to a database server.

Unit

DBLogDlg

Category

dialog and message routines

extern PACKAGE bool __fastcall LoginDialogEx(const System::AnsiString ADatabaseName, System::AnsiString &AUserName, System::AnsiString &APassword, bool NameReadOnly);

Description

Call LoginDialog to bring up the standard Login dialog box to prompt the user for a valid user name and password. The ADatabaseName parameter specifies the database for which access is being requested. It corresponds to the DatabaseName property of the TDatabase object. The NameReadOnly parameter specifies whether the user can change the user name from within the dialog.

The dialog returns the user name and password as the AUserName and APassword parameters.

LoginDialog returns false if the user cancels out of the dialog. If LoginDialog returns true, the application can attempt to connect to the database server using the supplied user name and password.


LogN

See also

Calculates log base N.

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall LogN(Extended Base, Extended X);

Description

The LogN function returns the log base N of X.


LowerCase

See also 	Example

Converts an ASCII AnsiString to lowercase.

Unit

SysUtils

Category

String handling routines

extern PACKAGE System::AnsiString __fastcall LowerCase(const System::AnsiString S);

Description

LowerCase returns an AnsiString with the same text as the AnsiString passed in S, but with all letters converted to lowercase. The conversion affects only 7-bit ASCII characters between 'A' and 'Z'. To convert 8-bit international characters, use AnsiLowerCase.


MatchesMask

See also

Indicates whether a file name conforms to the format specified by a filter AnsiString.

Unit

Masks

Category

file name utilities

extern PACKAGE bool __fastcall MatchesMask(const System::AnsiString Filename, const System::AnsiString Mask);

Description

Call MatchesMask to check the Filename parameter using the Mask parameter to describe valid values. A valid mask consists of literal characters, sets, and wildcards.

Each literal character must match a single character in the AnsiString. The comparison to literal characters is case-insensitive.

Each set begins with an opening bracket ([) and ends with a closing bracket (]). Between the brackets are the elements of the set. Each element is a literal character or a range. Ranges are specified by an initial value, a dash (-), and a final value. Do not use spaces or commas to separate the elements of the set. A set must match a single character in the AnsiString. The character matches the set if it is the same as one of the literal characters in the set, or if it is in one of the ranges in the set. A character is in a range if it matches the initial value, the final value, or falls between the two values. All comparisons are case-insensitve. If the first character after the opening bracket of a set is an exclamation point (!), then the set matches any character that is not in the set.

Wildcards are asterisks (*) or question marks (?). An asterisk matches any number of characters. A question mark matches a single arbitrary character.

MatchesMask returns true if the AnsiString matches the mask. MatchesMask returns false if the AnsiString does not match the mask. MatchesMask raises an exception if the mask is syntactically invalid.

Note:	The Filename parameter does not need to be a file name. MatchesMask can be used to check AnsiStrings against any syntactically correct mask.

Note:	MatchesMask is only available in the client server and Enterprise versions.


MaxIntValue

See also

Returns the largest signed value in an integer array.

Unit

Math

Category

statistical routines

extern PACKAGE int __fastcall MaxIntValue(const int * Data, const int Data_Size);

Description

Call MaxIntValue to obtain the largest integer from the Data array.


MaxValue

See also

Returns the largest signed value in an array.

Unit

Math

Category

statistical routines

extern PACKAGE double __fastcall MaxValue(const double * Data, const int Data_Size);

Description

MaxValue returns the largest signed value in the Data array.


Mean

See also

Returns the average of all values in an array.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall Mean(const double * Data, const int Data_Size);

Description

Mean calculates the arithmetic average of all the values in the Data array parameter.


MeanAndStdDev procedure
MeanAndStdDev

See also

Calculates the mean and standard deviation of array elements.

Unit

Math

Category

statistical routines

extern PACKAGE void __fastcall MeanAndStdDev(const double * Data, const int Data_Size, Extended &Mean, Extended &StdDev);

Description

MeanAndStdDev calculates Mean and standard deviation in one pass. Using this is twice as fast as calculating them separately. Precision may be lost when the Mean is very large (> 10e7) or the variance is very small.


MessageDlg

See also 	Example

Displays a message dialog box in the center of the screen.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE int __fastcall MessageDlg(const System::AnsiString Msg, TMsgDlgType DlgType, TMsgDlgButtons Buttons, int HelpCtx);

Description

Call MessageDlg to bring up a message box and obtain the user's response. The message box displays the value of the Msg parameter.  Use the AType parameter to indicate the purpose of the dialog.  Use the AButtons parameter to indicate what buttons should appear in the message box.  Use the HelpCtx parameter to specify the context ID for the help topic that should appear when the user clicks the help button or presses F1 while the dialog is displayed.

MessageDlg returns the value of the button the user selected. These are the possible return values:

Return values
mrNone	mrAbort	mrYes
mrOk	mrRetry	mrNo
mrCancel	mrIgnore	mrAll


MessageDlgPos

See also 	Example

Displays a message dialog box at the specified screen coordinates.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE int __fastcall MessageDlgPos(const System::AnsiString Msg, TMsgDlgType DlgType, TMsgDlgButtons Buttons, int HelpCtx, int X, int Y);

Description

Call MessageDlgPos to bring up a message box at a particular location. The message box displays the value of the Msg parameter.  Use the AType parameter to indicate the purpose of the dialog.  Use the AButtons parameter to indicate what buttons should appear in the message box.  Use the HelpCtx parameter to specify the context ID for the help topic that should appear when the user clicks the help button or presses F1 while the dialog is displayed.  Use the X and Y parameters to specify the screen coordinates where the dialog should appear.

MessageDlgPos returns the value of the button the user selected. These are the possible return values:

Return values
mrNone	mrAbort	mrYes
mrOk	mrRetry	mrNo
mrCancel	mrIgnore	mrAll


MessageDlgPosHelp

See also

Displays a message dialog box whose help is supplied in a named help file.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE int __fastcall MessageDlgPosHelp(const System::AnsiString Msg, TMsgDlgType DlgType, TMsgDlgButtons Buttons, int HelpCtx, int X, int Y, const System::AnsiString HelpFileName);

Description

Call MessageDlgPosHelp to bring up a message box when the associated help comes from a help file other than the default help file. The message box displays the value of the Msg parameter.  Use the AType parameter to indicate the purpose of the dialog.  Use the AButtons parameter to indicate what buttons should appear in the message box.  Use the HelpCtx parameter to specify the context ID for a help topic in the file specified by the HelpFileName parameter.  This help topic appears when the user clicks the help button or presses F1 while the dialog is displayed.  Use the X and Y parameters to specify the screen coordinates where the dialog should appear.

MessageDlgPosHelp returns the value of the button the user selected. These are the possible return values:

Return values
mrNone	mrAbort	mrYes
mrOk	mrRetry	mrNo
mrCancel	mrIgnore	mrAll


MinimizeName

See also

Returns a file name for display purposes, adding ellipses if necessary to maintain a length limit.

Unit

filectrl

Category

file name utilities

extern PACKAGE System::AnsiString __fastcall MinimizeName(const System::AnsiString Filename, Graphics::TCanvas * Canvas, int MaxLen);

Description

Call MinimizeName to ensure that a file name fits in the alloted display space.  If the file name passed as the Filename parameter is longer than MaxLen pixels when written to the canvas specified by the Canvas parameter, MinimizeName will remove portions of the path and replace them by ellipses in order to shorten the resulting AnsiString.


MinIntValue

See also

Returns the smallest signed value in an integer array.

Unit

Math

Category

statistical routines

extern PACKAGE int __fastcall MinIntValue(const int * Data, const int Data_Size);

Description

Call MinIntValue to obtain the smallest integer in the Data array.


MinValue

See also

Returns smallest signed value in an array.

Unit

Math

Category

statistical routines

extern PACKAGE double __fastcall MinValue(const double * Data, const int Data_Size);

Description

MinValue returns the smallest signed value in the Data array.


MomentSkewKurtosis procedure
MomentSkewKurtosis

Calculates the mean, variance, skew, and kurtosis.

Unit

Math

Category

statistical routines

extern PACKAGE void __fastcall MomentSkewKurtosis(const double * Data, const int Data_Size, Extended &M1, Extended &M2, Extended &M3, Extended &M4, Extended &Skew, Extended &Kurtosis);

Description

MomentSkewKurtosis calculates the core factors of statistical analysis: the first four moments plus the coefficients of skewness and kurtosis. M1 is the mean. M2 is the variance. Skew reflects symmetry of distribution. Kurtosis reflects flatness of distribution.


Move procedure
Move

Example

Copies bytes from a source to a destination.

Unit

System

Category

miscellaneous routines

extern PACKAGE void __fastcall Move(const void *Source, void *Dest, int Count);

Description

Move copies Count bytes from Source to Dest. No range-checking is performed.

Move compensates for overlaps between the source and destination blocks. Whenever possible, use SizeOf to determine the count.


MoveWindowOrg procedure
MoveWindowOrg

See also

Changes the location of the point (0,0) within a device context.

Unit

Controls

Category

graphics utilities

extern PACKAGE void __fastcall MoveWindowOrg(HDC DC, int DX, int DY);

Description

Call MoveWindowOrg to change the location of where items are drawn on the canvas of an object.  When drawing to a canvas, objects specify the location of the image they draw as a set of coordinates, which are offsets from the upper left corner.  MoveWindowOrg allows the same drawing code to draw its image in a different location.  The DC parameter is a handle to the device context of the canvas, printer, or window  where the image is to be drawn.  The DX and DY parameters specify the number of pixels to move the location of the (0,0) point on that drawing surface.

MoveWindowOrg is especially useful when playing metafiles, which draw to a particular position on a canvas, because it provides the ability to play the metafile to a different location on the canvas.


MSecsToTimeStamp

See also

Converts the number of milliseconds into a TTimeStamp value.

Unit

SysUtils

Category

date/time routines

extern PACKAGE TTimeStamp __fastcall MSecsToTimeStamp(System::Comp MSecs);

Description

Call MSecsToTimeStamp to convert MSecs, a number of milliseconds, into the number of days represented, plus the number of milliseconds remaining. The days and milliseconds are expressed as a TTimeStamp value, where the Date field is the number of days and the Time field is the remainder in milliseconds.


NativeCompareStr

See also

Compares AnsiStrings based on a database locale and is case sensitive.

Unit

DBTables

Category

BDE support routines

extern PACKAGE int __fastcall NativeCompareStr(void * Locale, const System::AnsiString S1, const System::AnsiString S2, int Len);

Description

NativeCompareStr compares S1 to S2, up to a length of Len characters.  If the Len parameter is 0, NativeCompareStr compares the AnsiStrings up to their entire length. The comparison is perfomed with case sensitivity. The compare operation is controlled by the locale specified as the Locale parameter. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2	= 0


NativeCompareStrBuf

See also

Compares null-terminated strings based on a database locale and is case sensitive.

Unit

DBTables

Category

BDE support routines

extern PACKAGE int __fastcall NativeCompareStrBuf(void * Locale, char * const S1, char * const S2, int Len);

Description

NativeCompareStrBuf compares up to the first Len characters of S1 to those of S2, with case sensitivity. If the Len parameter is 0, NativeCompareStrBuf compares the strings up to their entire length. The The compare operation is controlled by the locale specified as the Locale parameter. The return value is:

Condition	Return Value
S1 > S2	> 0
S1 < S2	< 0
S1 = S2	= 0


NativeCompareText

See also

Compares AnsiStrings based on a database locale and is not case sensitive.

Unit

DBTables

Category

BDE support routines

extern PACKAGE int __fastcall NativeCompareText(void * Locale, const System::AnsiString S1, const System::AnsiString S2, int Len);

Description

NativeCompareText compares up to the first Len characters of S1 to those of S2, without case sensitivity. If the Len parameter is 0, NativeCompareText compares the AnsiStrings up to their entire length. The compare operation is controlled by the locale specified as the Locale parameter. NativeCompareText returns a value less than 0 if S1 < S2, a value greater than 0 if S1 > S2, and returns 0 if S1 = S2.


NativeCompareTextBuf

See also

Compares null-terminated strings based on a database locale and is not case sensitive.

Unit

DBTables

Category

BDE support routines

extern PACKAGE int __fastcall NativeCompareTextBuf(void * Locale, char * const S1, char * const S2, int Len);

Description

NativeCompareTextBuf compares up to the first Len characters of S1 to those of S2, without case sensitivity. If the Len parameter is 0, NativeCompareTextBuf compares the strings up to their entire length. The compare operation is controlled by the locale specified as the Locale parameter. NativeCompareTextBuf returns a value less than 0 if S1 < S2, a value greater than 0 if S1 > S2, and returns 0 if S1 = S2.


NativeToAnsi

See also

Converts an AnsiString from the character set of the given locale to the ANSI character set.

Unit

DBTables

Category

BDE support routines

extern PACKAGE void __fastcall NativeToAnsi(void * Locale, char * NativeStr, System::AnsiString &AnsiStr);

Description

Call NativeToAnsi to convert an AnsiString represented in the character set of the Locale parameter to the ANSI character set (used internally by the VCL). The resulting AnsiString is returned as the AnsiStr parameter.

Use NativeToAnsi to convert AnsiStrings retrieved from a database table into AnsiStrings that can be displayed in the user interface.


NativeToAnsiBuf procedure
NativeToAnsiBuf

See also

Converts a string from the character set of a specified locale into the ANSI character set.

Unit

DBTables

Category

BDE support routines

extern PACKAGE void __fastcall NativeToAnsiBuf(void * Locale, char * Source, char * Dest, int Len);

Description

Call NativeToAnsiBuf to convert a character sequence in the character set of the Locale parameter to the ANSI character set (used internally by the VCL). The resulting string is copied into the buffer pointed to by the Dest parameter. Use the Len parameter to specify the size of this buffer.

Use NativeToAnsiBuf to convert strings from a database table into the ANSI character set so that they can be displayed in the user interface.


NewItem

See also

Creates and initializes a menu item.

Unit

Menus

Category

menu support routines

extern PACKAGE TMenuItem * __fastcall NewItem(const System::AnsiString ACaption, TShortCut AShortCut, bool AChecked, bool AEnabled, Classes::TNotifyEvent &AOnClick, Word hCtx, const System::AnsiString AName);

Description

Call NewItem to create and intialize a menu item when constructing a menu programatically at runtime.

•	The ACaption parameter indicates the string that should appear for the menu item.

•	The AShortCut parameter indicates any associated shortcut.

•	The AChecked parameter indicates whether the menu item appears with a check mark.

•	The AEnabled parameter specifies whether the menu item is enabled or grayed.

•	The AOnClick parameter specifies an event handler that executes when the user clicks the menu item.

•	The hCtx parameter specifies the help context ID for the menu item.

•	The AName parameter specifies the name of the menu item, which can be used to refer to the menu item in code.

Once a menu item has been created using NewItem, it can be added to an array and passed to the NewMenu or NewPopupMenu function if it is a top-level menu item, or to the NewSubMenu function if it is a submenu item.


NewLine

See also

Creates a menu item for a separator.

Unit

Menus

Category

menu support routines

extern PACKAGE TMenuItem * __fastcall NewLine(void);

Description

Call NewLine to create a separator that devides the items in a menu into logical groups. Once the menu item for the separator has been created using NewLine, it can be added to an array and passed to the NewPopupMenu function if it should appear in a popup menu, or to the NewSubMenu function if it should appear in a submenu.


NewMenu

See also

Creates and initializes a main menu.

Unit

Menus

Category

menu support routines

extern PACKAGE TMainMenu* __fastcall NewMenu(Classes::TComponent* Owner, const System::AnsiString AName, TMenuItem* const * Items, const int Items_Size);

Description

Call NewMenu to create and initialize a main menu containing the top level menu items passed in the Items parameter. Use the AName parameter to specify the name of the menu object, and the Owner parameter to specify the form which contains the menu.

To create the menu items for the Items parameter, use the NewItem function.


NewPopupMenu

See also

Creates and initializes a popup menu.

Unit

Menus

Category

menu support routines

extern PACKAGE TPopupMenu* __fastcall NewPopupMenu(Classes::TComponent* Owner, const System::AnsiString AName, TPopupAlignment Alignment, bool AutoPopup, TMenuItem* const * Items, const int Items_Size);

Description

Call NewPopupMenu to create and initialize a popup menu containing the menu items passed as the Items parameter. Use the AName parameter to specify the name of the popup menu and the Owner parameter to specify its Owner. The Alignment parameter determines where the menu appears relative to the mouse when the user right clicks on the control that uses the menu, and the AutoPopup paramter specifies whether the menu should appear automatically when the user right clicks the associated control. NewPopupMenu does not associate the popup menu with any control.

To create the menu items for the Items parameter, use the NewItem function.


NewStr

Allocates an AnsiString on the heap.

Unit

SysUtils

Category

backward compatibility routines

extern PACKAGE System::PAnsiString __fastcall NewStr(const System::AnsiString S);

Description

Do not use NewStr in new applications.  This function is provided for backward compatibility only.


NewSubMenu

See also

Creates and initializes a menu item that represents a submenu.

Unit

Menus

Category

menu support routines

extern PACKAGE TMenuItem * __fastcall NewSubMenu(const System::AnsiString ACaption, Word hCtx, const System::AnsiString AName, TMenuItem * const * Items, const int Items_Size);

Description

Call NewSubMenu to create a menu item that represents a submenu when constructing a menu programatically at runtime.

•	The ACaption parameter indicates the AnsiString that should appear in the parent menu for the submenu.

•	The hCtx parameter specifies the help context ID for the menu item.

•	The AName parameter specifies the name of the menu item, which can be used to refer to the menu item in code.

•	The Items parameter specifies an array of menu items that make up the submenu and that appear when the user clicks the submenu item in the parent menu.

Once a submenu has been created using NewSubMenu, it can be added to an array and passed to the NewMenu or NewPopupMenu function if it should appear in a top-level menu, or to the NewSubMenu function if it should appear in another submenu.


Norm

See also

Returns the Euclidean 'L-2' norm.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall Norm(const double * Data, const int Data_Size);

Description

Norm returns the Euclidean 'L-2' norm for the values in the Data array. The 'L-2' norm is the square root of the sum of squares.


Now

See also 	Example

Returns the current date and time.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall Now(void);

Description

Returns the current date and time, corresponding to Date + Time.


NumberOfPeriods

See also

Returns the number of payment periods for an investment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall NumberOfPeriods(Extended Rate, Extended Payment, Extended PresentValue, Extended FutureValue, TPaymentTime PaymentTime);

Description

NumberOfPeriods computes the number of payment periods required for an investment of PresentValue to reach a value of FutureValue, while making regular payments of Payment and accruing interest at the rate of Rate per compounding period. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (by entering a value of 1or 0, respectively).


ObjectBinaryToText procedure
ObjectBinaryToText

See also

Converts the binary representation of an object into more readily understandable text.

Unit

Classes

Category

streaming utilities

extern PACKAGE void __fastcall ObjectBinaryToText(TStream* Input, TStream* Output);

Description

Call ObjectBinaryToText to convert the representation of an object as it is saved in files and memory streams into a text version that can be understood by human readers. ObjectBinaryToText creates a TReader object for the Input stream, and uses this to read the binary representation of the object. A symbolic text representation is then written to the Output stream.

Use the WriteComponent method of the Input stream to write the binary representation before calling ObjectBinaryToText.


ObjectResourceToText procedure
ObjectResourceToText

See also

Converts the binary representation of an object resource into more readily understandable text.

Unit

Classes

Category

streaming utilities

extern PACKAGE void __fastcall ObjectResourceToText(TStream* Input, TStream* Output);

Description

Call ObjectResourceToText to convert the representation of an object as it is saved in module resource files into a text version that can be understood by human readers. ObjectResourceToText is the same as ObjectBinaryToText, except that it reads from a stream that includes a resource header.

ObjectResourceToText converts the binary version of a form, as stored in a .dfm file, into the text version that can be seen by right clicking the form and choosing View As Text.

Use the WriteComponentRes method of the Input stream to write the binary representation before calling ObjectResourceToText.


ObjectTextToBinary procedure
ObjectTextToBinary

See also

Converts a symbolic text representation of an object into the binary version that is used by the VCL to save the object to files or memory streams.

Unit

Classes

Category

streaming utilities

extern PACKAGE void __fastcall ObjectTextToBinary(TStream* Input, TStream* Output);

Description

Call ObjectTextToBinary to create the internal representation of a VCL object from a symbolic text representation. ObjectTextToBinary creates a TWriter object for the Output stream, and uses this to write the binary representation of the object from the symbolic representation that is read from the Input stream. Use the ReadComponent method of the output stream to obtain the actual object.


ObjectTextToResource procedure
ObjectTextToResource

See also

Converts a symbolic text representation of an object into an internal binary representation.

Unit

Classes

Category

streaming utilities

extern PACKAGE void __fastcall ObjectTextToResource(TStream* Input, TStream* Output);

Description

Call ObjectTextToResource to create a VCL object from the representation of an object as it is saved in module resource files. ObjectTextToResource is the same as ObjectTextToBinary, except that it skips over any object headers and includes a resource header instead. Use the ReadComponentRes method of the output stream to obtain the actual object.

ObjectTextToResource converts the text version of a form that can be seen by right clicking the form and choosing View As Text into the binary version which is stored in a .dfm file.


OleCheck procedure
OleCheck

See also

Throws an EOleSysError exception if the result code indicates an error.

Unit

ComObj

Category

COM utilities

extern PACKAGE void __fastcall OleCheck(HRESULT Result);

Description

OleCheck is used to wrap many COM routines, so that if that routine fails, users will have an opportunity to handle it in the resulting exception that is thrown.

If ECode is a value less than zero, OleCheck throws an EOleSysError exception specifying the error code.


OleError procedure
OleError

See also

Throws an EOleSysError exception.

Unit

ComObj

Category

COM utilities

extern PACKAGE void __fastcall OleError(HRESULT ErrorCode);

Description

OleError throws an EOleSysError exception from an error code passed in as the ErrorCode parameter.

OleError is used internally by the VCL to catch failed function calls by throwing an EOleSysError exception that indicates the cause of the failure as an error code.


OleStrToString

See also

Copies data received from OLE to an AnsiString.

Unit

System

Category

COM utilities

extern PACKAGE AnsiString __fastcall OleStrToString(wchar_t * Source);

Description

OleStrToString copies data received from an OLE function or method into an AnsiString.


OleStrToStrVar procedure
OleStrToStrVar

See also

Copies an OLE string to an existing AnsiString.

Unit

System

Category

COM utilities

extern PACKAGE void __fastcall OleStrToStrVar(wchar_t * Source, AnsiString &Dest);

Description

The OleStrToStrVar converts OLE string data into an existing AnsiString variable.


OutOfMemoryError procedure
 AOutOfMemoryError

See also

Throws an EOutOfMemory exception.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE void __fastcall OutOfMemoryError(void);

Description

Call OutOfMemoryError to throw the EOutOfMemory exception. Calling OutOfMemoryError results in smaller code size than creating the exception directly in code.


ParamCount

See also 	Example

Returns the number of parameters passed on the command line.

Unit

System

Category

command line utilities

extern PACKAGE int __fastcall ParamCount(void);

Description

ParamCount returns the number of parameters passed to the program on the command line. Separate parameters with spaces or tabs. Use double quotes to wrap multiple words as one parameter (such as long file names containing spaces).


ParamStr

See also 	Example

Returns a specified parameter from the command-line.

Unit

System

Category

command line utilities

extern PACKAGE AnsiString __fastcall ParamStr(int Index);

Description

Index is an expression of type Integer. ParamStr returns the parameter from the command line that corresponds to Index, or an empty AnsiString if Index is greater than ParamCount. For example, an Index value of 2 returns the second command-line parameter.

ParamStr(0) returns the path and file name of the executing program (for example, C:\TEST\MYPROG.EXE).


PasswordDialog

Example

Displays a dialog box that prompts the user for the password of a local password-protected table.

Unit

DBPWDlg

Category

BDE support routines

extern PACKAGE bool __fastcall PasswordDialog(Classes::TComponent ASession);

Description

Use PasswordDialog to allow the user to enter a password for a password-protected Paradox or Dbase table.

ASession is the name of the session instance to which the password is passed. If the user clicks OK in the dialog box, PasswordDialog returns true. Otherwise it returns false.

Note:	When an application opens a Paradox table that requires a password, the user is prompted to enter a password unless the Session component already has a valid password for that table.


Payment

See also

Calculates a fully amortized payment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall Payment(Extended Rate, int NPeriods, Extended PresentValue, Extended FutureValue, TPaymentTime PaymentTime);

Description

Payment calculates the fully amortized payment of borrowing PresentValue dollars at Rate percent per period over NPeriods. It assumes that interest is paid at the end of each period.

FutureValue is the value that the investment will reach at some point. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (enter a value of 1 for the beginning or 0 for the end).


PeriodPayment

See also

Returns the principal amount from a full payment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall PeriodPayment(Extended Rate, int Period, int NPeriods, Extended PresentValue, Extended FutureValue, TPaymentTime PaymentTime);

Description

PeriodPayment gives the part of the payment that is principal. The InterestPayment function gives the part of the payment that is interest.

The Rate parameter is the interest rate. Period is the number of periods into the loan for which the principal is desired, and NPeriods is the number of periods of the loan. FutureValue is the value the investment will reach at some point. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (enter a value of 1 for the beginning or 0 for the end).


Point

See also	Example

Creates a TPoint structure from a pair of coordinates.

Unit

Classes

Category

type conversion routines

extern PACKAGE tagPOINT __fastcall Point(int AX, int AY);

Description

Call Point to create a TPoint that represents the specified coordinates. Use Point to construct parameters for functions that require TPoint, rather than setting up local variables for each parameter.


Poly

Evaluates a uniform polynomial of one variable at the value X.

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall Poly(Extended X, const double * Coefficients, const int Coefficients_Size);

Description

Call Poly to evaluate the polynomial represented by the Coefficients parameter at the point where the variable equals the value of the X parameter. The coefficients are ordered in increasing powers of X:

    Coefficients[0] + Coefficients[1]*X + ... + Coefficients[N]*(X**N)


PopnStdDev

Calculates the population standard deviation.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall PopnStdDev(const double * Data, const int Data_Size);

Description

PopnStdDev calculates the population standard deviation (the square root of the population variance) of all values in the Data array parameter. This function is used in some business and financial calculations.


PopnVariance

Calculates the population variance.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall PopnVariance(const double * Data, const int Data_Size);

Description

PopnVariance calculates the population variance of all values in the Data array parameter, using the n method (biased): TotalVariance / n.


Power

See also

Raises Base to any power.

Unit

Math

Category

arithmetic routines

extern PACKAGE Extended __fastcall Power(Extended Base, Extended Exponent);

Description

Power raises Base to any power. For fractional exponents or exponents greater than MaxInt, Base must be greater than 0.


PresentValue

See also

Calculates the present value of an investment.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall PresentValue(Extended Rate, int NPeriods, Extended Payment, Extended FutureValue, TPaymentTime PaymentTime);

Description

PresentValue calculates the present value of an investment where Payment is received for NPeriods and is discounted at the rate of Rate per period. FutureValue is the value the investment may reach at some point. PaymentTime indicates whether the cash flows occur at the beginning or end of the period (enter a value of 1 for the beginning or 0 for the end).


Printer

See also	Example

Returns a global instance of TPrinter to manage interaction with the printer.

Unit

Printers

Category

miscellaneous routines

extern PACKAGE TPrinter * __fastcall Printer(void);

Description

Printer creates an instance of a global TPrinter object the first time it is called. Use the Printer function to print using the TPrinter object.

Printer is declared in the Printers unit. To use the Printer function and the TPrinter object, include Printers.hpp in the source file.


ProcessPath procedure
ProcessPath

See also

Parses a file name into its constituent parts.

Unit

filectrl

Category

file name utilities

extern PACKAGE void __fastcall ProcessPath(const System::AnsiString EditText, char &Drive, System::AnsiString &DirPart, System::AnsiString &FilePart);

Description

Call ProcessPath to parse a file name into its drive, path, and file name.  Pass the full file name that should be parsed as the EditText parameter.  ProcessPath returns the indicated drive, directory, and file name as the Drive, DirPart, and FilePart parameters.


ProgIDToClassID

See also

Returns the class ID (CLSID) TGUID that corresponds to the AnsiString specified as the ProgID parameter.

Unit

ComObj

Category

COM utilities

extern PACKAGE GUID __fastcall ProgIDToClassID(const System::AnsiString ProgID);

Description

ProgIDToClassID retrieves, from the registry, the CLSID for a given programmatic ID. The ProgID parameter specifies the programmatic ID for which the CLSID is requested. A programmatic ID is a string that is associated with the CLSID in the registry.

If ProgIDToClassID succeeds it returns a the requested CLSID. If ProgIDToClassID fails an EOleSysError exception is raised with an error code indicating the cause of the error. The error code possibilites are as follows:

Error code	Meaning
CO_E_CLASSSTRING	The registered CLSID for the ProgID is invalid.
REGDB_E_WRITEREGDB	An error occurred writing the CLSID to the registry.
Note:	If the ProgID cannot be found in the registry, ProgIDToClassID creates an OLE 1 CLSID for the ProgID and a CLSID entry in the registry.


QuotedStr

See also

Returns the quoted version of an AnsiString.

Unit

SysUtils

Category

String handling routines

extern PACKAGE System::AnsiString __fastcall QuotedStr(const System::AnsiString S);

Description

Use QuotedStr to convert the AnsiString S to a quoted AnsiString. A quote character (') is inserted at the beginning and end of S, and each single quote character in the AnsiString is repeated.

Note:	When working with multi-byte character systems (MBCS), use AnsiQuotedStr instead.


RadToCycle

See also

Converts radians to cycles.

Unit

Math

Category

measurement conversion routines

extern PACKAGE Extended __fastcall RadToCycle(Extended Radians);

Description

Use RadToCycle to convert angles measured in radians into cycles, where

cycles = radians/(2pi).


RadToDeg

See also

Converts radians to degrees.

Unit

Math

Category

measurement conversion routines

extern PACKAGE Extended __fastcall RadToDeg(Extended Radians);

Description

Use RadToDeg to convert angles measured in radians to degrees, where

degrees = radians(180/pi).


RadToGrad

See also

Converts radians to grads.

Unit

Math

Category

measurement conversion routines

extern PACKAGE Extended __fastcall RadToGrad(Extended Radians);

Description

Use RadToGrad to convert angles measured in radians to grads, where

grads = radians(200/pi).


RaiseLastWin32Error procedure
RaiseLastWin32Error

See also

Throws an exception for the last occurring Win32 error.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE void __fastcall RaiseLastWin32Error(void);

Description

Call RaisLastWin32Error to throw an EWin32Error exception for the last Windows API call that failed. RaiseLastWin32Error retrieves the code for the last occuring Win32 error, if any. If Windows returns a previously occurring error code, RaiseLastWin32Error throws an EWin32Error exception with the error code and message associated with that error.


RandG

Generates random numbers with Gaussian distribution.

Unit

Math

Category

random number routines

extern PACKAGE Extended __fastcall RandG(Extended Mean, Extended StdDev);

Description

RandG produces random numbers with Gaussian distribution about the Mean. This is useful for simulating data with sampling errors and expected deviations from the Mean.


Randomize procedure
Randomize

See also

Initializes the random number generator with a random value.

Unit

System

Category

random number routines

extern PACKAGE void __fastcall Randomize(void);

Description

Randomize initializes the built-in random number generator with a random value (obtained from the system clock).

The random number generator should be initialized by making a call to Randomize, or by assigning a value to RandSeed.


ReadComponentRes

See also

Reads components and their properties from a specified Windows resource.

Unit

Classes

Category

streaming utilities

TComponent* __fastcall ReadComponentRes(TComponent* Instance);

Description

Call ReadComponentRes to create a component from its representation in a Windows resource header. The ResName parameter is the name assigned to the resource for the component. The Instance parameter is an instance of the component that should be filled in with the attributes of the saved resource. Instance must be an object of the same class as the saved resource, or one of its descendants.  Create an instance of the appropriate type of object, and then call ReadComponentRes to read in its property settings. If Instance is NULL, the object class is read from the resource.

ReadComponentRes returns an instance of the component that was read from the resource.


ReadComponentResEx

See also

Reads a component from a resource.

Unit

Classes

Category

streaming utilities

extern PACKAGE TComponent * __fastcall ReadComponentResEx(int HInstance, const System::AnsiString ResName);

Description

Use ReadComponentResEx to load a component from a resource stored in a particular module (as opposed to ReadComponentRes which assumes the current module).

The Hinstance parameter is the instance handle for the module that stores the component as a resource.  The ResName parameter is the name assigned to the resource for the component.

ReadComponentResEx returns an instance of the component that was read from the resource.


ReadComponentResFile

See also

Reads components and their properties from a specified Windows resource file.

Unit

Classes

Category

streaming utilities

extern PACKAGE TComponent* __fastcall ReadComponentResFile(const System::AnsiString FileName, TComponent* Instance);

Description

Call ReadComponentResFile to create a component and its children from their representation in a Windows resource file. The FileName parameter is the name of the compiled resource file that contains the component resource. The Instance parameter is an instance of the type of component that should be read. Create an instance of the appropriate type of object, and then call ReadComponentResFile to read in its property settings. If Instance is NULL, the object class is read from the resource.

ReadComponentResFile returns an instance of the component that was read from the resource file.


Rect

See also	Example

Creates a TRect structure from a set of coordinates.

Unit

Classes

Category

type conversion routines

extern PACKAGE Windows::TRect __fastcall Rect(int ALeft, int ATop, int ARight, int ABottom);

Description

Call Rect to create a TRect that represents the rectangle with the specified coordinates. Use Rect to construct parameters for functions that require TRect, rather than setting up local variables for each parameter.


RegisterClass procedure
RegisterClass

See also

Registers a class of persistent object so that it’s class type can be retrieved.

Unit

Classes

Category

class handling routines

extern PACKAGE void __fastcall RegisterClass(System::TMetaClass* AClass);

Description

Call RegisterClass to register a class with the streaming system. Form classes and component classes that are referenced in a form declaration (instance variables) are automatically registered.  Any other classes used by an application must be explicitly registered by calling RegisterClass.  When classes are registered, the class type can be obtained from the class name by calling the FindClass or GetClass function. If a class is not registered, GetClass returns NULL when passed the class name, while FindClass throws an exception.

The AClass parameter is the class that is descended from TPersistent. Put the call to RegisterClass in a Register in the namespace of the compilation unit that defines the class.

If the class is already registered, RegisterClass does nothing. If a different class with the same name is already registered, RegisterClass throws an EFilerError exception.

Note:	Registering a component using the RegisterNoIcon or RegisterComponents method does not automatically register the class. It is still necessary to call RegisterClass for components.


RegisterClassAlias procedure
RegisterClassAlias

See also

Registers a class that is identical to another class except for the name.

Unit

Classes

Category

class handling routines

extern PACKAGE void __fastcall RegisterClassAlias(System::TMetaClass* AClass, const System::AnsiString Alias);

Description

Component writers call RegisterClassAlias to register custom classes that are identical to another persistent class except for the name.


RegisterClasses procedure
RegisterClasses

See also

Registers a set of classes.

Unit

Classes

Category

class handling routines

extern PACKAGE void __fastcall RegisterClasses(System::TMetaClass* const * AClasses, const int AClasses_Size);

Description

Call RegisterClasses to register a set of custom classes in a single line. Each class in the list is registered by calling RegisterClass. References to registered classes can be obtained from the class name by calling the FindClass or GetClass function.


RegisterComponentEditor procedure
RegisterComponentEditor

See also

Registers an editor so that it is available at design time.

Unit

DsgnIntf

Category

design tool registration routines

extern PACKAGE void __fastcall RegisterComponentEditor(System::TMetaClass* ComponentClass, System::TMetaClass* ComponentEditor);

Description

Call RegisterComponentEditor to allow objects instantiated from the specified ComponentClass or one of its descendants use the editor at design time. A registered component editor is created for each component of ComponentClass that is selected in the form designer.  When the component is double-clicked the Edit method of the component editor is called.  When the user right-clicks the component, the GetVerbCount and GetVerb methods of the editor are called to build context menu.

If no component editor is registered, the component uses the default component editor. The default component editor (TDefaultEditor) implements Edit to search the properties of the component and generate the OnCreate, OnChanged, or OnClick event (whichever it finds first).


RegisterComponents procedure
RegisterComponents

See also 	Example

Registers a set of components so that they all appear on the same page of the component palette.

Unit

Classes

Category

component registration routines

extern PACKAGE void __fastcall RegisterComponents(const System::AnsiString Page, System::TMetaClass* const * ComponentClasses, const int ComponentClasses_Size);

Description

Call RegisterComponents to install a set of components in the IDE. Once a component is registered, it appears on the component palette, where it can be selected and placed on forms. Registered components can communicate with the Object Inspector to allow the user to get and set properties and events.

Set the Page parameter to the name of the page on the component palette where the components should appear. If the named page already exists, the components are added to that page. If the named page does not exist, a new palette page with that name is created.

Call RegisterComponents from the implementation of the Register routine in one of the namespaces associated with the custom components. The units that define the components must then be compiled into a package and the package must be installed before the custom components are added to the component palette.


RegisterFields procedure
RegisterFields

See also

Registers a set of field components so that they appear in the Dataset designer.

Unit

Db

Category

component registration routines

extern PACKAGE void __fastcall RegisterFields(System::TMetaClass* const * FieldClasses, const int FieldClasses_Size);

Description

Call RegisterFields to allow custom descendents of TField to appear in the field type drop down of the new field dialog box.


RegisterLibraryExpert procedure
RegisterLibraryExpert

Registers an expert so that it is installed when the package is installed.

Unit

ExptIntf

Category

design tool registration routines

extern PACKAGE void __fastcall RegisterLibraryExpert(TIExpert* Expert);

Description

Call RegisterLibrary to register an expert for a package so that it appears in the New Items dialog. If the package already has a registered expert, RegisterLibraryExpert does nothing.


RegisterNoIcon procedure
RegisterNoIcon

See also

Registers a set of components but does not add them to the component palette.

Unit

Classes

Category

component registration routines

extern PACKAGE void __fastcall RegisterNoIcon(System::TMetaClass* const * ComponentClasses, const int ComponentClasses_Size);

Description

Call RegisterNoIcon to register a set of custom components so that objects from that class can use the Object Inspector. Because the components are not added to the component palette, instances of components registered using RegisterNoIcon must be explicitly created by calling the Create method, ususally from another component.

The ComponentClasses parameter is an array of custom classes that are descended from TComponent. Put the call to RegisterNoIcon in the Register routine.

To add the components to the component palette, use RegisterComponents instead.


RegisterNonActiveX procedure
RegisterNonActiveX

See also

Prevents a set of components from being made available to the ActiveX wizard.

Unit

Classes

Category

component registration routines

TActiveXRegType = (axrComponentOnly, axrIncludeDescendants);

extern PACKAGE void __fastcall RegisterNonActiveX(System::TMetaClass* const * ComponentClasses, const int ComponentClasses_Size, TActiveXRegType AxRegType);

Description

Call RegisterNonActiveX to prevent a registered set of custom components from being converted into ActiveX controls using the ActiveX wizard. The components must still be registered using RegisterComponents or RegisterNoIcon if they are to work with the Object Inspector.

The ComponentClasses parameter is an array of custom classes that are descended from TComponent. The AxRegType parameter indicates whether only the components in the ComponentClasses array should be blocked from the ActiveX wizard (AxRegType = axrComponentOnly), or whether their descendants should be prohibited from becoming ActiveX controls as well (AxRegType = axrIncludeDescendants).

Put the call to RegisterNonActiveX in the Register routine.

The TActiveXRegType type is the type of the AxRegType parameter. The following table lists the possible values:

Value	Meaning
axrComponentOnly	Only the component classes explicitly listed in the ComponentClasses parameter will be blocked from appearing in the ActiveX Wizard.
axrIncludeDescendants	All of the component classes listed in the ComponentClasses and any descendant of any of those component classes will be blocked from the Wizard.


RegisterPropertyEditor procedure
RegisterPropertyEditor

See also

Allows a component to bring up a custom property editor from the Object Inspector.

Unit

DsgnIntf

Category

design tool registration routines

extern PACKAGE void __fastcall RegisterPropertyEditor(Typinfo::PTypeInfo PropertyType, System::TMetaClass* ComponentClass, const System::AnsiString PropertyName, System::TMetaClass* EditorClass);

Description

Call RegisterPropertyEditor to associate the property editor class specified by the EditorClass parameter with the property type specified by the PropertyType parameter.

When a component is selected, the Object Inspector creates a property editor for each of the component's properties, based on the type of the property.  For example, if the property type is an Integer, the property editor for Integer will be created (by default that would be TIntegerProperty). Most properties do not need specialized property editors.  For example, if the property is an ordinal type the default property editor will restrict the range to the subtype range.

When a property type can not be properly edited using the default property editor or one of the existing property editors, use RegisterPropertyEditor to associate a custom property editor with the property type. This is typically because the property is an object.

When registering a property editor, set PropertyType to the type information pointer returned by the TypeInfo function. For example, TypeInfo(TPropertyObject). Set the ComponentClass parameter to restrict the property editor to a component class and its descendants. Setting ComponentClass to NULL associates the property editor with the property type for any component. Set the PropertyName parameter to restrict the property editor to properties with a specific name as well as the specified property type. Setting PropertyName to an empty string associates the property editor with any property of the specified type. Set the EditorClass parameter to the class of the property editor that should be displayed when the property is selected in the Object Inspector.


RemoveDir

See also

Deletes an existing empty directory.

Unit

SysUtils

Category

file management routines

extern PACKAGE bool __fastcall RemoveDir(const System::AnsiString Dir);

Description

Call RemoveDir to remove the directory specified by the Dir paramter.  The return value is true if a new directory was successfully deleted, false if an error occurred.  The directory must be empty before it can be successfully deleted.


RenameFile

See also 	Example

Changes a file name identified by OldName.

Unit

SysUtils

Category

file management routines

extern PACKAGE bool __fastcall RenameFile(const System::AnsiString OldName, const System::AnsiString NewName);

Description

RenameFile attempts to change the name of the file specified by OldFile to NewFile. If the operation succeeds, RenameFile returns true. If it cannot rename the file (for example, if a file called NewName already exists), it returns false.


SelectDirectory

See also 	Example

Brings up a dialog to allow the user to enter a directory name.

Unit

FileCtrl

Category

dialog and message routines

extern PACKAGE bool __fastcall SelectDirectory(System::AnsiString &Directory, TSelectDirOpts Options, int HelpCtx);

Description

Call SelectDirectory to let the user enter a directory name. Calling SelectDirectory displays the Select Directory dialog box. The directory passed to the function with the Directory parameter appears as the currently selected directory when the dialog box appears. The name of the directory the user selects becomes the value of Directory when the function returns. SelectDirectory does not change the value of the current directory.

The HelpCtx parameter is the help context ID number.

The Options parameter is a set of values. If Options is the empty set, the user can only select a directory that already exists. No edit box is provided for the user to enter a new directory name.

These are the possible values that can be added to the Options set:

Value	Meaning
sdAllowCreate	An edit box appears to allow the user to type in the name of a directory that does not exist. This option does not create a directory, but the application can access the Directory parameter to create the directory selected if desired.
sdPerformCreate	Used only when Options contains sdAllowCreate. If the user enters a directory name that does not exist, SelectDirectory creates it.
sdPrompt	Used when Options contains sdAllowCreate. Displays a message box that informs the user when the entered directory does not exist and asks if the directory should be created. If the user chooses OK, the directory is created if Options contains sdPerformCreate. If Options does not contain sdPerformCreate, the directory is not created: the application should create it when SelectDirectory returns.
The function returns true if the user selected a directory and chose OK, and false if the user chose Cancel or closed the dialog box without selecting a directory.


Set8087CW procedure
Set8087CW

See also	Example

Sets both the control word in the floating point unit and the variable Default8087CW declared in the system unit.

Unit

System

Category

miscellaneous routines

extern PACKAGE void __fastcall Set8087CW(Word NewCW);

Description

The floating point unit control word controls the precision of floating point calculcations, the rounding mode, and whether certain floating point operations trigger exceptions. See Intel's processor documentation for details.

This routine allows the programmer to have direct access to the CW. Be aware that using this routine to change the value of the 8087CW will change the behavior of the program’s FP calculations. It is the programmer’s responsibility to reset it.

For example, it is recommended that you disable all floating point exceptions when using OpenGL to render 3D graphics. To do this, call Set8087CW(0x133f) in your main form’s OnCreate event before calling any OpenGL functions.


SetCaptureControl procedure
SetCaptureControl

See also

Causes the specified control to receive all mouse messages.

Unit

Controls

Category

mouse handling utilities

extern PACKAGE void __fastcall SetCaptureControl(TControl * Control);

Description

Call SetCaptureControl to allow a control to capture the mouse.  When the control has the mouse captured, it receives all mouse messages until another control captures the mouse by a subsequent call to SetCaptureControl or until the application calls the Windows API function ReleaseCapture.

Note:	Many VCL controls call SetCapture internally in response to mouse events.  Applications should be careful when using this routine.


SetClipboard

See also

Replaces the single global clipboard instance with another clipboard object.

Unit

clipbrd

Category

clipboard routines

extern PACKAGE TClipboard * __fastcall SetClipboard(TClipboard * NewClipboard);

Description

Use SetClipboard to replace the global clipboard instance with a customized descendant of TClipboard.  SetClipboard returns the currently instantiated clipboard, if any.  After replacing the global clipboard instance using SetClipboard, an application must free the old clipboard which is returned.


SetCurrentDir

See also

Sets the current directory and returns true if successful.

Unit

SysUtils

Category

file management routines

extern PACKAGE bool __fastcall SetCurrentDir(const System::AnsiString Dir);

Description

The SetCurrentDir function sets the current directory. The return value is true if the current directory was successfully changed, or false if an error occurred.


SetMemoryManager procedure
SetMemoryManager

See also 	Example

Sets entry points of the memory manager.

Unit

System

Category

memory management routines

extern PACKAGE void __fastcall SetMemoryManager(const TMemoryManager &MemMgr);

Description

SetMemoryManager sets the entry points of the memory manager to the three functions specified by the MemMgr parameter. Use SetMemoryManager to change the memory allocation routines that are used for:

Allocation and deallocation of objects through constructors and destructors.

Allocation and deallocation of AnsiStrings.

The GetMem field of the MemMgr parameter must point to a function that allocates the given number of bytes and returns a pointer to the newly allocated block. The Size parameter passed to the GetMem function will never be zero. If the GetMem function cannot allocate a block of the given size, it should return NULL.

The FreeMem field of the MemMgr parameter must point to a function that deallocates the given block. The pointer parameter passed to the FreeMem function will never be NULL. If the FreeMem function successfully deallocates the given block, it should return zero. Otherwise, it should return a non-zero value.

The ReallocMem field of the MemMgr parameter must point to a function that reallocates the given block to the given new size. The pointer parameter passed to the ReallocMem function will never be NULL, and the Size parameter will never be zero. The ReallocMem function must reallocate the given block to the given new size, possibly moving the block if it cannot be resized in place. Any existing contents of the block must be preserved, but newly allocated space can be uninitialized. The ReallocMem function must return a pointer to the reallocated block, or NULL if the block cannot be reallocated.


SetOleFont procedure
SetOleFont

See also

SetOleFont connects an OLE font object to a TFont object and copies the properties of the OLE font object to the TFont.

Unit

AXCtrls

Category

COM utilities

virtual void __fastcall SetOleFont(const _di_IFontDisp OleFont) = 0;

Description

OLE conventions implement fonts as automation objects that contain the properties of the font.  This routine associates an OLE font object (the OleFont parameter) with a native VCL font (the Font parameter), allowing the font to be accessed by both OLE programs and VCL programs.  The TFont object is initialized to have the same properties as OleFont.

Call this method when you implement an automation method that takes an OLE font as a parameter, and which needs to pass the font along as a native TFont object.


SetOlePicture procedure
SetOlePicture

See also

Connects an OLE picture object to a TPicture object, and copies the properties of the OLE picture object to the TPicture.

Unit

AXCtrls

Category

COM utilities

virtual void __fastcall SetOlePicture(const _di_IPictureDisp OlePicture) = 0;

Description

OLE conventions implement pictures as automation objects that contain the properties of the picture.  This routine associates an OLE picture object (the OlePicture parameter) with a native VCL picture (the Picture parameter), allowing the picture to be accessed by both OLE programs and VCL programs.  The TPicture object is initialized to have the same properties as OlePicture.

Call this method when you implement an automation method that takes an OLE picture as a parameter, and which needs to pass the picture along as a native TPicture object.


ShortCut

See also 	Example

Creates a menu shortcut for a specified key combination.

Unit

Menus

Category

menu support routines

extern PACKAGE TShortCut __fastcall ShortCut(Word Key, Classes::TShiftState Shift);

Description

Call ShortCut to create a menu shortcut at runtime. Specify a Key value using a virtual key code. Specify the values for the Shift, Control, and Alt keys by using a set of type TShiftState. For example, to specify the Shift key, use the set [ssShift]. To specify a Shift and Ctrl key combination, use the set [ssShift, ssCtrl].

Assign the value returned by ShortCut as the value of the ShortCut property of a menu item.

Note:	TextToShortCut can also create a shortcut. TextToShortCut converts a string to a shortcut, so it can be used to let the user specify the shortcut. However, TextToShortCut executes much more slowly than ShortCut. Use ShortCut whenever possible.


ShortCutToKey procedure
ShortCutToKey

See also 	Example

Returns the virtual key code and shift state of a menu shortcut.

Unit

Menus

Category

menu support routines

extern PACKAGE void __fastcall ShortCutToKey(TShortCut ShortCut, Word &Key, Classes::TShiftState &Shift);

Description

Call ShortCutToKey to parse a menu shortcut into its virtual key code and shift state parts.


ShortCutToText

See also 	Example

Converts a menu shortcut into an AnsiString that describes the shortcut.

Unit

Menus

Category

menu support routines

extern PACKAGE System::AnsiString __fastcall ShortCutToText(TShortCut ShortCut);

Description

Call ShortCutToText to obtain a text description of the shortcut associated with a menu item. Use this function when the application needs to display a description of a shortcut to the user.


ShowException procedure
ShowException

Displays an exception message with its physical address

Unit

SysUtils

Category

exception handling routines

extern PACKAGE void __fastcall ShowException(System::TObject* ExceptObject, void * ExceptAddr);

Description

This routine displays the message associated with an exception, together with the exception's physical address. The exception's address can be used with Search | Find Error menu command to find the statement that threw the exception.


ShowMessage procedure
ShowMessage

See also 	Example

Displays a message box with an OK button.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE void __fastcall ShowMessage(const System::AnsiString Msg);

Description

Call ShowMessage to display a simple message box with an OK button. The Msg parameter is the message string that appears in the message box. The name of the application's executable file appears as the caption of the message box.

To display a message in a message box with other buttons, or with an icon, use the MessageDlg function.


ShowMessageFmt procedure
ShowMessageFmt

See also

Displays a message box with a formatted message.

Unit

Dialogs

Category

dialog and message routines

extern PACKAGE void __fastcall ShowMessageFmt(const System::AnsiString Msg, const System::TVarRec *Params, const int Params_Size);

Description

Call ShowMessageFmt to display a simple message box with an OK button. The Msg parameter is a format string for the message that appears in the message box. The Params parameter provides the parameters that are assembled into the message. The name of the application's executable file appears as the caption of the message box.

For more information about how messages are formatted, see Format Strings.

To display a message in a message box with other buttons, or with an icon, use the MessageDlg function.


SinCos procedure
SinCos

Returns sine and cosine of an angle.

Unit

Math

Category

trigonometry routines

extern PACKAGE void __fastcall SinCos(Extended Theta, Extended &Sin, Extended &Cos);

Description

SinCos is twice as fast as calling Sin and Cos separately for the same angle.


Sinh

Returns the hyperbolic sine of an angle.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall Sinh(Extended X);

Description

Sinh calculates the hyperbolic sine of X.


SLNDepreciation

See also

Returns the straight-line depreciation allowance of an asset.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall SLNDepreciation(Extended Cost, Extended Salvage, int Life);

Description

SLNDepreciation calculates the straight-line depreciation allowance for an asset over one period of its life. The function divides the Cost minus the Salvage by the number of years of useful Life of the asset. Cost is the amount initially paid for the asset. Salvage is the value of the asset at the end of its useful life.

To compute accelerated depreciation (allowing higher depreciation values in the first years of the assets life), use the SYDDepreciation function.


StdDev

Returns the sample standard deviation for elements in an array.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall StdDev(const double * Data, const int Data_Size);

Description

StdDev calculates the sample standard deviation (the square root of the sample variance) of all values in the Data array parameter. Data_Size indicates the index of the last element in the array (one less than the number of elements).


StrAlloc

Allocates a buffer for a null-terminated string and returns a pointer the first character of the string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrAlloc(Cardinal Size);

Description

This function allocates a buffer for a null-terminated string with a maximum length of Size - 1 (1 byte must be reserved for the termination character). The result points to the location where the first character of the string is to be stored. A 32-bit number giving the total amount of memory allocated is stored in the four bytes preceding the first character; it is equal to Size + 4. If space for a string is allocated with StrAlloc, it should be deallocated via StrDispose.

Since long strings are implicitly null terminated and dynamically allocated, the use of StrAlloc is in decline.


StrBufSize

Returns max number of characters that can be stored in a buffer allocated by StrAlloc.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE Cardinal __fastcall StrBufSize(char * Str);

Description

This number includes the termination character. If Str does not point to a string buffer allocated by StrAlloc, no error message is returned, and the result is unpredictable.


StrByteType

See also

Indicates whether a byte in a string is a single byte character, the first byte of a double byte character, or the second byte of a double byte character.

Unit

SysUtils

Category

MBCS utilities

extern PACKAGE TMbcsByteType __fastcall StrByteType(char * Str, Cardinal Index);

Description

Call ByteType to determine the type of the byte specified by the Index parameter, where 0 specifies the first byte in the string Str, 1 specifies the second byte, and so on.

If the system is not using a multi-byte character system (MBCS), ByteType always returns mbSingleByte. Otherwise, ByteType returns mbSingleByte if the indicated byte represents a complete character in Str, mbLeadByte if it represents the first byte of a double byte character, and mbTrailByte if it represents the second byte of a double byte character.

Note:	No checking is done to ensure that Index is less than the length of Str. It is the caller's responsibility to ensure that Index is not out of bounds.


StrCat

See also 	Example

Appends a copy of Source to the end of Dest and returns the concatenated string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrCat(char * Dest, char * Source);

Description

StrCat does not perform any length checking. The destination buffer must have room for at least StrLen(Dest)+StrLen(Source)+1 characters.

To check length, use the StrLCat function.


StrComp

See also 	Example

Compares Str1 to Str2

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall StrComp(char * Str1, char * Str2);

Description

Call StrComp to compare two null-terminated strings, with case sensitivity.  The return value is indicated in the following table:

Return value	Condition
<0	if Str1< Str2
=0	if Str1= Str2
>0	if Str1 > Str2
Note:	When working with International characters, use AnsiStrComp instead.


StrCopy

See also 	Example

Copies Source to Dest and returns Dest.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrCopy(char * Dest, char * Source);

Description

StrCopy does not perform any length checking. The destination buffer must have room for at least StrLen(Source)+1 characters.

For length checking, use the StrLCopy function.


StrDispose procedure
StrDispose

See also

Disposes of a string.

Unit

SysUtils

Category

backward compatibility routines

extern PACKAGE void __fastcall StrDispose(char * Str);

Description

StrDispose is provided for backward compatibility only. StrDispose disposes of a string on a heap that was previously allocated with StrAlloc or StrNew.

If Str is NULL, StrDispose does nothing.


StrECopy

See also 	Example

Copies Source to Dest and returns a pointer to the null character ending the string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrECopy(char * Dest, char * Source);

Description

StrECopy copies Source to Dest and returns StrEnd(Dest).

StrECopy does not perform any length checking. The destination buffer must have room for at least StrLen(Source)+1 characters.

Nested calls to StrECopy to concatenate a sequence of strings will run more efficiently than multiple calls to StrCat.


StrEnd

See also 	Example

Returns a pointer to the end of a null terminated string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrEnd(char * Str);

Description

StrEnd returns a pointer to the null character at the end of Str.


StrFmt

See also

Formats entries in an array.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE char * __fastcall StrFmt(char * Buffer, char * Format, const System::TVarRec * Args, const int Args_Size);

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the null-terminated format string Format; the results are returned in Buffer. The function result contains a pointer to the destination buffer.


StrIComp

See also 	Example

Compares Str1 to Str2 without case sensitivity.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall StrIComp(char * Str1, char * Str2);

Description

Call StrIComp to compare two strings without case sensitivity. StrIComp returns a value greater than 0 if Str1 > Str2, less than 0 if Str1 < Str2, and returns 0 if the strings are equal except for differences in case. When working with international characters, use AnsiStrIComp instead.


StringReplace

Returns an AnsiString with the occurrences of one substring replaced by another substring.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall StringReplace(const System::AnsiString S, const System::AnsiString OldPattern, const System::AnsiString NewPattern, TReplaceFlags Flags);

Description

StringReplace replaces occurrences of one substring, specified by OldPattern, with another substring, specified by NewPattern, in a given AnsiString. StringReplace assumes the AnsiString may contain Multibyte characters.

If the Flags parameter does not include rfReplaceAll, StringReplace only replaces the first occurrence of OldPattern in the AnsiString S. If the Flags parameter includes rfIgnoreCase, The string comparison operation is case insensitive.


StringToColor

See also

Translates an AnsiString representation of a color to the corresponding TColor value.

Unit

Graphics

Category

graphics utilities

extern PACKAGE TColor __fastcall StringToColor(const System::AnsiString S);

Description

Call StringToColor to reverse the translation performed by ColorToString. This method is useful for converting the strings entered by the user into useable TColor values.

The S parameter can be either the name of a built-in color constant such as 'clBtnFace', or the string representation of a valid TColor value such as '$02FF8800'.  StringToColor returns the TColor value that corresponds to the S parameter.

Note:	If the string identifier can only be the name of a color constant, use IdentToColor instead.


StringToCursor

See also

Returns a TCursor value given its string representation.

Unit

controls

Category

cursor management routines

extern PACKAGE TCursor __fastcall StringToCursor(const System::AnsiString S);

Description

Call StringToCursor to reverse the translation performed by CursorToString. This method is useful for converting the strings entered by the user into useable TCursor values.

The S parameter can be either the name of a built-in cursor constant such as 'crHelp', or the string representation of a valid TCursor value such as '10'.  StringToCursor returns the TCursor value that corresponds to the S parameter.

Note:	The value returned by StringToCursor is not guaranteed to be a valid cursor.  If the Cursors property of the global Screen variable does not include a corresponding entry, the value returned by StringToCursor can not be used to set the Cursor property of a control.


StringToGUID

See also

Converts an AnsiString to a GUID.

Unit

ComObj

Category

COM utilities

extern PACKAGE GUID __fastcall StringToGUID(const System::AnsiString S);

Description

StringToGUID converts an AnsiString, S, into the original CLSID.

If StringToGUID succeeds it returns a the requested CLSID. If StringToGUID fails an EOleSysError exception is thrown with an error code indicating the cause of the error.


StringToOleStr

See also

Allocates memory and copies an AnsiString to the OLE format.

Unit

System

Category

COM utilities

extern PACKAGE wchar_t * __fastcall StringToOleStr(const AnsiString Source);

Description

StringToOleStr allocates memory and copies string data from a native (Default Font) AnsiString into a format that can be passed to OLE functions.


StringToWideChar

Returns a UNICODE string from an AnsiString.

Unit

System

Category

wide character routines

extern PACKAGE wchar_t * __fastcall StringToWideChar(const AnsiString Source, wchar_t * Dest, int DestSize);

Description

StringToWideChar converts the AnsiString given by Source from ANSI to UNICODE and stores the result in the buffer given by Dest and DestSize. Following the call, the Dest buffer contains at most DestSize - 1 characters from the source string, terminated by a NULL wide character. The function result value is Dest.


StripHotKey

See also

Removes the hotkey character marker from a string.

Unit

Menus

Category

menu support routines

extern PACKAGE System::AnsiString __fastcall StripHotKey(const System::AnsiString Text);

Description

StripHotKey removes the & escape char that marks the hotkey character in the AnsiString.  When the current locale is an Asian locale, this function also looks for and removes parentheses around the hotkey, which are common in Asian locales.


StrLCat

See also 	Example

Appends a specified maximum number of characters to string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrLCat(char * Dest, char * Source, Cardinal MaxLen);

Description

StrLCat appends at most MaxLen - StrLen(Dest) characters from Source to the end of Dest and returns Dest. The SizeOf standard function can be used to determine the MaxLen parameter.


StrLComp

See also 	Example

Compares a specified maximum number of characters in two strings.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall StrLComp(char * Str1, char * Str2, Cardinal MaxLen);

Description

StrLComp compares Str1 to Str2, up to a maximum length of MaxLen characters. The return value is the same as StrComp.

Note:	When working with international characters, use AnsiStrLComp instead.


StrLCopy

See also 	Example

Copies a specified maximum number of characters from Source to Dest.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrLCopy(char * Dest, char * Source, Cardinal MaxLen);

Description

StrLCopy copies at most MaxLen characters from Source to Dest and returns Dest. The SizeOf standard function can be used to determine the MaxLen parameter.


StrLen

See also 	Example

Returns number of character in a string excluding the null terminator.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE Cardinal __fastcall StrLen(char * Str);

Description

StrLen returns the number of characters in Str, not counting the null terminator.


StrLFmt

See also

Formats a series of arguments from the open array specified.

Unit

SysUtils

Category

string formatting routines

extern PACKAGE char * __fastcall StrLFmt(char * Buffer, Cardinal MaxLen, char * Format, const System::TVarRec* Args, const int Args_Size);

Description

This function formats the series of arguments in the open array Args. Formatting is controlled by the null-terminated format string Format; the results are returned in Buffer, whose maximum length is given by MaxLen. The function result contains a pointer to the destination buffer.

For information on the format strings, see Format Strings.


StrLIComp

See also 	Example

Compares strings up to a specified maximum number of characters, not case sensitive.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE int __fastcall StrLIComp(char * Str1, char * Str2, Cardinal MaxLen);

Description

StrLIComp compares Str1 to Str2 , up to a maximum length of MaxLen characters, without case sensitivity.

The return value is the same as StrComp.

Note:	When working with international characters, use AnsiStrLIComp instead.


StrLower

See also 	Example

Converts a string to lowercase.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrLower(char * Str);

Description

StrLower converts Str to lowercase and returns Str.


StrMove

See also 	Example

Copies specified number of characters to string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrMove(char * Dest, char * Source, Cardinal Count);

Description

StrMove copies exactly Count characters from Source to Dest and returns Dest. Source and Dest can overlap.


StrNew

See also 	Example

Allocates space on and copies a string to the heap; returns a pointer to the string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrNew(char * Str);

Description

StrNew allocates a copy of Str on the heap.

If Str is NULL or points to an empty string, StrNew returns a pointer to a new empty string.

Otherwise, StrNew makes a duplicate of Str, obtaining space with a call to StrAlloc, and returns a pointer to the duplicated string.

The allocated space is the length of Str + 5 bytes.


StrPas

See also

Converts null-terminated Str to an AnsiString.

Unit

SysUtils

Category

backward compatibility routines

extern PACKAGE System::AnsiString __fastcall StrPas(char * Str);

Description

This function is provided for backwards compatibility only. To convert a null terminated string to an AnsiString, use a typecast or an assignment.


StrPCopy

See also 	Example

Copies an AnsiString to a null-terminated string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrPCopy(char * Dest, const System::AnsiString Source);

Description

StrPCopy copies an AnsiString Source into a null-terminated string Dest.

StrPCopy does not perform any length checking.

The destination buffer must have room for at least Length(Source)+1 characters.


StrPLCopy

Copies characters from an AnsiString into a null-terminated string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrPLCopy(char * Dest, const System::AnsiString Source, Cardinal MaxLen);

Description

StrPLCopy copies a maximum of MaxLen characters from the an AnsiString Source into the null-terminated string Dest. Dest is also returned as the function result.


StrPos

See also 	Example

Returns a pointer to the first occurance of STR2 in STR1.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrPos(char * Str1, char * Str2);

Description

StrPos returns a pointer to the first occurrence of Str2 in Str1. If Str2 does not occur in Str1, StrPos returns NULL.


StrRScan

See also 	Example

Returns a pointer to the last occurance of Chr in Str.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrRScan(char * Str, char Chr);

Description

StrRScan returns a pointer to the last occurrence of Chr in Str.

If Chr does not occur in Str, StrRScan returns NULL. The null terminator is considered to be part of the string.


StrScan

See also 	Example

Returns a pointer to first occurrence of a specified character in a string.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrScan(char * Str, char Chr);

Description

If Chr does not occur in Str, StrScan returns NULL. The null terminator is considered to be part of the string.


StrToCurr

See also

Converts an AnsiString to a Currency object.

Unit

SysUtils

Category

floating-point conversion routines

extern PACKAGE System::Currency __fastcall StrToCurr(const System::AnsiString S);

Description

Call StrToCurr to convert an AnsiString that represents a floating-point value to the corresponding Currency object. The AnsiString must consist of an optional sign (+ or -), an AnsiString of digits with an optional decimal point, and an optional 'E' or 'e' followed by a signed integer. Leading and trailing blanks in the AnsiString are ignored.

The DecimalSeparator global variable defines the character that must be used as a decimal point. Thousand separators and currency symbols are not allowed in the AnsiString. If the AnsiString doesn't contain a valid value, an EConvertError exception is thrown.


StrToDate

See also 	Example

Converts an AnsiString object to a TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall StrToDate(const System::AnsiString S);

Description

The date in the AnsiString must be a valid date.

The AnsiString must consist of two or three numbers, separated by the character defined by the DateSeparator global variable. The order for month, day, and year is determined by the ShortDateFormat global variable--possible combinations are m/d/y, d/m/y, and y/m/d.

If the AnsiString contains only two numbers, it is interpreted as a date (m/d or d/m) in the current year. Year values between 0 and 99 are assumed to be in the current century.

If the given AnsiString does not contain a valid date, an EConvertError exception is raised.

Note:	The format of the date AnsiString varies when the value of any of the date and time typed constants are changed.


StrToDateTime

See also 	Example

Converts an AnsiString object into TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall StrToDateTime(const System::AnsiString S);

Description

The AnsiString specified as the S parameter must be in the MM/DD/YY HH:MM:SS format. Specifying AM or PM as part of the time is optional, as are the seconds. Use 24-hour time (7:45 PM is entered as 19:45, for example) AM or PM is not specified.

Note:	If the date and time typed constants are redefined for the system, the AnsiString returned by this function will change.


StrToFloat

Converts a given AnsiString to a floating-point value.

Unit

SysUtils

Category

floating-point conversion routines

extern PACKAGE Extended __fastcall StrToFloat(const System::AnsiString S);

Description

The AnsiString must consist of an optional sign (+ or -), an AnsiString of digits with an optional decimal point, and an optional 'E' or 'e' followed by a signed integer. Leading and trailing blanks in the AnsiString are ignored.

The DecimalSeparator global variable defines the character that must be used as a decimal point. Thousand separators and currency symbols are not allowed in the AnsiString. If the AnsiString doesn't contain a valid value, an EConvertError exception is thrown.


StrToInt

See also 	Example

Converts an AnsiString representing an integer (decimal or hex notation) to a number.

Unit

SysUtils

Category

type conversion routines

extern PACKAGE int __fastcall StrToInt(const System::AnsiString S);

Description

StrToInt converts an AnsiString representing an integer-type number in either decimal or hexadecimal notation into a number. If the AnsiString does not represent a valid number, StrToInt throws an EConvertError exception.


StrToIntDef

See also 	Example

Converts an AnsiString to a number.

Unit

Sysutils

Category

type conversion routines

extern PACKAGE int __fastcall StrToIntDef(const System::AnsiString S, int Default);

Description

If S does not represent a valid number, StrToIntDef returns the number passed in Default.


StrToTime

See also 	Example

Converts an AnsiString to a TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall StrToTime(const System::AnsiString S);

Description

The AnsiString must consist of two or three numbers, separated by the character defined by the TimeSeparator global variable, optionally followed by an AM or PM indicator. The numbers represent hour, minute, and (optionally) second, in that order. If the time is followed by AM or PM, it is assumed to be in 12-hour clock format. If no AM or PM indicator is included, the time is assumed to be in 24-hour clock format. If the given AnsiString does not contain a valid time, an EConvertError exception is thrown.


StrUpper

See also 	Example

Returns a string in upper case.

Unit

SysUtils

Category

string handling routines (null-terminated)

extern PACKAGE char * __fastcall StrUpper(char * Str);

Description

StrUpper converts Str to uppercase and returns Str.


Sum

See also

Returns the sum of the elements from an array.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall Sum(const double * Data, const int Data_Size);

Description

Sum calculates the sum of all the values in the Data array parameter.


SumInt

See also

Returns the sum of the elements from an integer array.

Unit

Math

Category

statistical routines

extern PACKAGE int __fastcall SumInt(const int * Data, const int Data_Size);

Description

Sum calculates the sum of all the values in the Data array parameter.


SumOfSquares

Returns the sum of the squared values from a data array.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall SumOfSquares(const double * Data, const int Data_Size);

Description

SumOfSquares returns the sum of the squares of the Data values: Data[0]2 + Data[1]2 + Data[2]2...


SumsAndSquares procedure
SumsAndSquares

Returns the sum of the values and the sum of the squared values in an array.

Unit

Math

Category

statistical routines

extern PACKAGE void __fastcall SumsAndSquares(const double * Data, const int Data_Size, Extended &Sum, Extended &SumOfSquares);

Description

SumsAndSquares returns the sum of the Data values in Sum and the sum of the squares in SumOfSquares. This function is faster than calculating the sums separately.


SYDDepreciation

See also

Calculates depreciation for an asset.

Unit

Math

Category

business and finance routines

extern PACKAGE Extended __fastcall SYDDepreciation(Extended Cost, Extended Salvage, int Life, int Period);

Description

SYDDepreciation (for "sum-of-years-digits depreciation") calculates depreciation amounts for an asset using an accelerated depreciation method. This allows for higher depreciation in the earlier years of an asset's life.

Cost is the initial cost of the asset. Salvage is the value of the asset at the end of its life expectancy. Life is the length of the asset's life expectancy. Period is the period for which to calculate the depreciation.


SysErrorMessage

Converts Win32 API error codes into AnsiStrings.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE System::AnsiString __fastcall SysErrorMessage(int ErrorCode);

Description

The SysErrorMessage returns an error message string that corresponds to the specified Win32 API routine error code. This function can be used to convert Windows error codes into AnsiStrings.


SysFreeMem

See also

Frees the memory pointed to by the specified pointer.

Unit

System or ShareMem

Category

memory management routines

extern PACKAGE int __fastcall SysFreeMem(void * P);

Description

When implementing a custom memory manager, use SysFreeMem to free the memory pointed to by the P parameter. Include the System unit if the memory was allocated from the global heap. Include the ShareMem unit instead if the memory was shared with other processes.


SysGetMem

See also

Allocates the specified number of bytes and returns a pointer to it.

Unit

System or ShareMem

Category

memory management routines

extern PACKAGE void * __fastcall SysGetMem(int Size);

Description

When implementing a custom memory manager, use SysGetMem to dynamically allocate Size bytes of memory. If the System unit is included, the memory is allocated from the Global heap. If the ShareMem unit is included instead, the memory is reference counted memory that can be shared with other processes.


SysReallocMem

See also

Returns a pointer to the specified number of bytes, preserving the values pointed to by the Pointer parameter.

Unit

System or ShareMem

Category

memory management routines

extern PACKAGE void * __fastcall SysReallocMem(void * P, int Size);

Description

When implementing a custom memory manager, use SysReallocMem to change the size of a dynamically allocated chunk of memory. The memory pointed to by the P parameter is freed, but the values are copied to the newly allocated memory that is returned. If Size is less than the number of bytes pointed to by P, only the first Size bytes are preserved. Otherwise, the entire value of the memory pointed to by P is copied to the newly allocated memory.

If the System unit is included, both the return value and P must point to memory from the global heap. If the ShareMem unit is included instead, P and the return value point to memory that can be shared with other processes.


SystemTimeToDateTime

See also 	Example

Converts a _SYSTEMTIME value into a TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall SystemTimeToDateTime(const _SYSTEMTIME &SystemTime);

Description

Call SystemTimeToDateTime to convert a value from Windows 32's TSystemTime API format to a TDateTime object format.


Tan

Returns the tangent of X.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall Tan(Extended X);

Description

Tan returns the tangent of X. Tan(X) = Sin(X) / Cos(X).


Tanh

Returns the hyperbolic tangent of X.

Unit

Math

Category

trigonometry routines

extern PACKAGE Extended __fastcall Tanh(Extended X);

Description

Tanh calculates the hyperbolic tangent of X.


TerminateExtension

See also

Indicates whether an ISAPI or NSAPI application is ready to be shut down.

Unit

ISAPIApp

BOOL __fastcall TerminateExtension(int dwFlags);

Description

Do not call TerminateExtension. TerminateExtension is exported by ISAPI and NSAPI DLLs. It provides an entry point that is called by ISAPI or NSAPI web servers when they are ready to shut down the ISAPI or NSAPI application, to check whether it would cause problems to do so.


TextToFloat

Returns a floating point value from a null-terminated string.

Unit

SysUtils

Category

floating point conversion routines

extern PACKAGE bool __fastcall TextToFloat(char * Buffer, void *Value, TFloatValue ValueType);

Description

TextToFloat converts the null-terminated string given by Buffer to a floating-point value which is returned in the variable given by Value. The Value parameter must be a variable of type Extended or Currency, as indicated by the ValueType parameter. The return value is true if the conversion was successful, or false if the string is not a valid floating-point value. For further details, see the description of StrToFloat.


TextToShortCut

See also 	Example

Creates a menu shortcut from a text AnsiString.

Unit

Menus

Category

menu support routines

extern PACKAGE TShortCut __fastcall TextToShortCut(System::AnsiString Text);

Description

Call TextToShortCut to create a menu shortcut from a descriptive AnsiString. For example, an application can allow users to specify what they want the shortcut to be in an edit box control, then call TextToShortCut to create a menu shortcut for the value entered by the user.

Note:	TextToShortCut executes slowly. When possible, use the ShortCut function to create a menu shortcut instead.


Time

See also 	Example

Returns the current time.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall Time(void);

Description

Time returns the current time as a TDateTime object.


TimeStampToDateTime

See also

Converts a TTimeStamp value into the corresponding TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::TDateTime __fastcall TimeStampToDateTime(const TTimeStamp &TimeStamp);

Description

Call TimeStampToDateTime to convert a TTimeStamp value into a TDateTime object. TTimeStamp values represent time as separate date and time values, where the date is the number of calandar days since the start of the current calandar (that is, January 1, 0001 would have a value of 1), and time is the number of milliseconds since midnight. TDateTime objects represent time as the number of days (including fractional days) that have elapsed since 12:00 am on December 30, 1899.


TimeStampToMSecs

See also

Converts a TTimeStamp value into an absolute number of milliseconds.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::Comp __fastcall TimeStampToMSecs(const TTimeStamp &TimeStamp);

Description

Call TimeStampToMSecs to convert TimeStamp, a TTimeStamp value, into the total number of milliseconds that comprise the Date field plus the number of milliseconds given in the Time field.


TimeToStr

See also 	Example

Returns an AnsiString from a TDateTime object.

Unit

SysUtils

Category

date/time routines

extern PACKAGE System::AnsiString __fastcall TimeToStr(System::TDateTime Time);

Description

TimeToStr converts the Time parameter, a TDateTime object, to an AnsiString. The conversion uses the format specified by the LongTimeFormat global variable. Change the format of the AnsiString display by changing the values of some of the date and time variables.


TotalVariance

Returns the statistical variance from an array of values.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall TotalVariance(const double * Data, const int Data_Size);

Description

TotalVariance returns the sum of the squares of the difference between each Data value and the mean of the data values.

{Total Variance: SUM(i=1,N)[(X(i) - Mean)**2]}


Trim

See also

Trims an AnsiString of leading and trailing spaces and control characters.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall Trim(const System::AnsiString S);

Description

Trim trims leading and trailing spaces and control characters from the given AnsiString S.


TrimLeft

See also

Trims a given AnsiString of leading spaces and control characters.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall TrimLeft(const System::AnsiString S);

Description

TrimLeft returns a copy of a given AnsiString that has leading spaces and control characters trimmed.


TrimRight

See also

Trims a given AnsiString of trailing spaces and control characters.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall TrimRight(const System::AnsiString S);

Description

The TrimRight returns a copy of a given AnsiString that has trailing spaces and control characters trimmed.


UniqueString procedure
UniqueString

Makes a given AnsiString unique.

Unit

System

Category

miscellaneous routines

extern PACKAGE void __fastcall UniqueString(AnsiString &str);

Description

Following a call to SetString, S is guaranteed to reference a unique AnsiString; that is, an AnsiString with a reference count of one. For normal string handling, there is no need to ever call UniqueString. Only in cases where an application uses AnsiString::c_str() and then modifies the contents of the string must UniqueString be used.


UnloadPackage procedure
 AUnloadPackage

See also

Unloads a package.

Unit

SysUtils

Category

package support routines

extern PACKAGE void __fastcall UnloadPackage(Windows::HINST Module);

Description

Call UnloadPackage to unload a package that was loaded using the LoadPackage function. UnloadPackage performs any finalization of units contained in the package and then unloads the package DPL.


UnregisterClass procedure
UnregisterClass

See also

Unregisters an object class.

Unit

Classes

Category

class handling routines

extern PACKAGE void __fastcall UnRegisterClass(System::TMetaClass* AClass);

Description

Call UnregisterClass to unregister a an object class. When a class is unregistered, its name can be reused to register another object class. Unregistered classes can not be obtained from the class name using the GetClass function.


UnregisterClasses procedure
UnregisterClasses

See also

Unregisters a set of classes.

Unit

Classes

Category

class handling routines

extern PACKAGE void __fastcall UnRegisterClasses(System::TMetaClass* const * AClasses, const int AClasses_Size);

Description

Call UnregisterClasses to unregister several persistent object classes in a single line. When a class is unregistered, its name can be reused to register another object class. Unregistered classes can not be obtained from the class name using the GetClass function.


UnregisterModuleClasses procedure
UnregisterModuleClasses

See also

Unregisters all classes defined in a specified module.

Unit

Classes

Category

class handling routines

extern PACKAGE void __fastcall UnRegisterModuleClasses(Windows::HINST Module);

Description

Call UnregisterModuleClasses to unregister all object classes that were registered by the module with the handle specified by the Module parameter. When a class is unregistered, its name can be reused to register another object class. Unregistered classes can not be obtained from the class name using the GetClass function.


UpCase

See also 	Example

Converts a character to uppercase.

Unit

System

Category

miscellaneous routines

extern PACKAGE char __fastcall UpCase(char Ch);

Description

UpCase converts a character to uppercase. Ch is an expression of type Char. Character values not in the range a..z are unaffected.


UpperCase

See also 	Example

Returns a copy of an AnsiString in uppercase.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall UpperCase(const System::AnsiString S);

Description

UpperCase returns a copy of an Ansistring containing the same text as S, but with all 7-bit ASCII characters between 'a' and 'z' converted to uppercase. To convert 8-bit international characters, use AnsiUpperCase instead.


ValidParentForm

See also

Returns the form or property page that contains a specified control.

Unit

Forms

Category

miscellaneous routines

extern PACKAGE TCustomForm* __fastcall ValidParentForm(Controls::TControl* Control);

Description

Call ValidParentForm to obtain the descendant of TCustomForm that contains the control specified by the Control parameter. If the control is not contained in a VCL form (for example, an ActiveX control embedded in another type of window), ValidParentFrom throws an EInvalidOperation exception.


VarArrayCreate

See also 	Example

Creates a variant array.

Unit

System

Category

variant support routines

extern PACKAGE Variant __fastcall VarArrayCreate(const int * Bounds, const int Bounds_Size, int VarType);

Description

VarArrayCreate creates a variant array with the bounds given by Bounds and the element type given by VarType. The Bounds parameter must contain an even number of values, and each pair of values specify the upper and lower bounds of one dimension of the array. The element type of the array, given by the VarType parameter, must be one of the TVarData type codes, and cannot include the varArray or varByRef bits. The element type cannot be varString. To create a variant array of strings use the varOleStr type code. If the element type is varVariant, the elements of the array are themselves variants and can in turn contain variant arrays.

Note:	Variant arrays with an element type of varByte are the preferred method of passing binary data between OLE Automation controllers and servers. Such arrays are subject to no translation of their data, and can be efficiently accessed using the VarArrayLock and VarArrayUnlock routines.


VarArrayDimCount

See also

Returns number of dimensions of a variant array.

Unit

System

Category

variant support routines

extern PACKAGE int __fastcall VarArrayDimCount(const Variant &A);

Description

VarArrayDimCount returns the number of dimensions of the given variant. The resulting value is zero if the given variant is not a variant array.


VarArrayHighBound

See also

Returns high bound for a dimension in a variant array.

Unit

System

Category

variant support routines

extern PACKAGE int __fastcall VarArrayHighBound(const Variant &A, int Dim);

Description

VarArrayHighBound returns the high bound of the given dimension in the given variant array. The Dim parameter should be 1 for the leftmost dimension, 2 for the second leftmost dimension, and so on. An EVariantError exception is raised if the variant given by A is not an array, or if the dimension specified by Dim does not exist.


VarArrayLock

See also 	Example

Locks a variant array and returns a pointer to the data.

Unit

System

Category

variant support routines

extern PACKAGE void * __fastcall VarArrayLock(const Variant &A);

Description

VarArrayLock locks the given variant array and returns a pointer to the data stored in the array. While locked, a variant array can not be resized and any calls to VarArrayRedim will fail. Once locked, a variant array must later be unlocked using VarArrayUnlock. An EVariantError exception is thrown if the variant given by A is not an array.

The pointer returned by VarArrayLock points to an array of elements in which the leftmost dimension increases first. In other words, the dimensions of the returned array pointer are reversed from the dimensions of the variant array.

Once it is verified that a variant array has the correct bounds and dimensions, VarArrayLock can be used to gain direct access to the array data which results in much improved performance.


VarArrayLowBound

See also

Returns the low bound of a dimension in a variant array.

Unit

System

Category

variant support routines

extern PACKAGE int __fastcall VarArrayLowBound(const Variant &A, int Dim);

Description

VarArrayLowBound returns the low bound of the given dimension in the given variant array. The Dim parameter should be 1 for the leftmost dimension, 2 for the second leftmost dimension, and so on. An EVariantError exception is raised if the variant given by A is not an array, or if the dimension specified by Dim does not exist.


VarArrayOf

See also

Creates and fills a one-dimensional variant array.

Unit

System

Category

variant support routines

extern PACKAGE Variant __fastcall VarArrayOf(const Variant * Values, const int Values_Size);

Description

VarArrayOf returns a one-dimensional variant array with the elements given by the Values parameter. The low bound of the returned array is zero, the high bound is the number of values given by the Values parameter less one, and the element type is Variant.


VarArrayRef

See also

Returns a reference to the passed variant array.

Unit

System

Category

variant support routines

extern PACKAGE Variant __fastcall VarArrayRef(const Variant &A);

Description

Use this function to reference a variant array when a referenced variant array is expected in some API call.


VarArrayUnlock procedure
VarArrayUnlock

See also

Unlocks a variant array.

Unit

System

Category

variant support routines

extern PACKAGE void __fastcall VarArrayUnlock(const Variant &A);

Description

VarArrayUnlock unlocks a variant array that was previously locked by VarArrayLock. An EVariantError exception is raised if the variant given by A is not an array.


VarAsType

See also

Converts a variant to specified type.

Unit

System

Category

variant support routines

extern PACKAGE Variant __fastcall VarAsType(const Variant &V, int VarType);

Description

VarAsType converts the variant given by V to the type given by VarType. The resulting value is a variant of the type given by VarType. The VarType parameter must be one of the TVarData type codes, and cannot include the varArray or varByRef bits. An EVariantError exception is thrown if the variant cannot be converted to the given type.

VarCast provides the same functionality as VarAsType.


VarFromDateTime

See also

Returns a variant containing a specified data and time.

Unit

System

Category

variant support routines

extern PACKAGE Variant __fastcall VarFromDateTime(TDateTime DateTime);

Description

VarFromDateTime returns a Variant object that contains the given date and time of the TDateTime object, DateTime. The type code of the resulting variant is varDate.


Variance

Calculates statistical sample variance from an array of data.

Unit

Math

Category

statistical routines

extern PACKAGE Extended __fastcall Variance(const double * Data, const int Data_Size);

Description

Variance calculates the sample variance of all values in the Data array parameter, using the n-1 method (unbiased).


VarIsArray

See also

Returns true if the specified variant is an array.

Unit

System

Category

variant support routines

extern PACKAGE bool __fastcall VarIsArray(const Variant &A);

Description

VarIsArray returns true if the given variant is an array. Otherwise, the function result is false.


VarIsEmpty

See also

Returns true if the specified variant is Unassigned.

Unit

System

Category

variant support routines

extern PACKAGE bool __fastcall VarIsEmpty(const Variant &V);

Description

VarIsEmpty returns true if the given variant contains the value Unassigned. If the variant contains any other value, the function result is false.


VarIsNull

See also

Returns true is the specified variant is Null.

Unit

System

Category

variant support routines

extern PACKAGE bool __fastcall VarIsNull(const Variant &V);

Description

VarIsNull returns true if the given variant contains the value Null. If the variant contains any other value, the function result is false.


VarToDateTime

See also

Converts a specified Variant to a TDateTime object.

Unit

System

Category

variant support routines

extern PACKAGE TDateTime __fastcall VarToDateTime(const Variant &V);

Description

VarToDateTime converts the given Variant to a TDateTime object. An EVariantError exception is raised if the conversion fails.


VarToStr

Converts a Variant object to an AnsiString object.

Unit

System

Category

variant support routines

extern PACKAGE AnsiString __fastcall VarToStr(const Variant &V);

Description

VarToStr converts the data in Variant to an AnsiString.


VarType

See also

Returns type code of a specified Variant.

Unit

System

Category

variant support routines

extern PACKAGE int __fastcall VarType(const Variant &V);

Description

VarType returns the type code of the given variant. The resulting value is constructed from the following constants declared in the System unit.

const

  varEmpty    = $0000;

  varNull     = $0001;

  varSmallint = $0002;

  varInteger  = $0003;

  varSingle   = $0004;

  varDouble   = $0005;

  varCurrency = $0006;

  varDate     = $0007;

  varOleStr   = $0008;

  varDispatch = $0009;

  varError    = $000A;

  varBoolean  = $000B;

  varVariant  = $000C;

  varUnknown  = $000D;

  varByte     = $0011;

  varString   = $0100;

  varTypeMask = $0FFF;

  varArray    = $2000;

  varByRef    = $4000;

The lower twelve bits of a variant type code (the bits defined by the varTypeMask bit mask) define the type of the variant. The varArray bit is set if the variant is an array of the given type. The varByRef bit is set if the variant is a reference to a value of the given type as opposed to an actual value.

The following table describes the meaning of each of the variant type codes.

VarType	Contents of variant
varEmpty	The variant is Unassigned.
varNull	The variant is Null.
VarSmallint	16-bit signed integer (type Smallint).
varInteger	32-bit signed integer (type Integer).
varSingle	Single-precision floating-point value (type Single).
varDouble	Double-precision floating-point value (type Double).
varCurrency	Currency floating-point value (type Currency).
varDate	Date and time value (type TDateTime).
varOLEStr	Reference to a dynamically allocated UNICODE string.
varDispatch	Reference to an OLE automation object (an IDispatch interface pointer).
varError	Operating system error code.
varBoolean	16-bit boolean (type WordBool).
varUnknown	Reference to an unknown OLE object (an IUnknown interface pointer).
varString	Reference to a dynamically allocated AnsiString.
The value returned by VarType corresponds to the VType field of a TVarData record.

The type of a variant can be changed using VarAsType.


WideCharLenToString

See also

Converts Unicode characters to an AnsiString.

Unit

System

Category

wide character routines

extern PACKAGE AnsiString __fastcall WideCharLenToString(wchar_t * Source, int SourceLen);

Description

WideCharLenToString converts SourceLen Unicode characters from the buffer given by Source to an AnsiString. The function uses the WideCharToMultiByte Win32 API to perform the actual conversion.


WideCharToString

See also

Converts null-terminated Unicode string to an AnsiString.

Unit

System

Category

wide character routines

extern PACKAGE AnsiString __fastcall WideCharToString(wchar_t * Source);

Description

WideCharToString converts the given null-terminated Unicode string to an AnsiString. The function uses the WideCharToMultiByte Win32 API to perform the actual conversion.


WideCharToStrVar procedure
WideCharToStrVar

See also

Converts Unicode string to a single byte character data.

Unit

System

Category

wide character routines

extern PACKAGE void __fastcall WideCharToStrVar(wchar_t * Source, AnsiString &Dest);

Description

WideCharToStrVar converts UNICODE string data into single byte character data, and copies the result into the provided destination AnsiString variable. The source must be null-terminated.


Win32Check

See also

Checks the return value of a Windows API call and throws an appropriate exception when it indicates failure.

Unit

SysUtils

Category

exception handling routines

extern PACKAGE BOOL __fastcall Win32Check(BOOL RetVal);

Description

Call Win32Check with the return value of a Windows API call that returns a Boolean to indicate success or failure. If the Windows API returns false (indicating failure), Win32Check calls RaiseLastWin32Error to throw an exception.  If the Windows function returns true, Win32Check returns true.


WrapText

Splits an AnsiString into multiple lines as its length approaches a specified size.

Unit

SysUtils

Category

string handling routines

extern PACKAGE System::AnsiString __fastcall WrapText(const System::AnsiString Line, const System::AnsiString BreakStr, const TSysCharSet &BreakChars, int MaxCol);

Description

WrapText scans an AnsiString for occurrences of any of the characters specified by nBreakChars and inserts a line-break, specified by BreakStr, at the last occurence of a character in nBreakChars before MaxCol. Line is the text WrapText scans. MaxCol is the maximum line length.

WrapText does not insert a break into an embedded quoted string (both single quotes and double quotes are supported).

As an example, the following settings wrap the text into two lines at the last space character:

TSysCharSet bchars

bchars << '.' << '-' << ' ';

WrapText("The rain in Spain falls mainly on the plain.", "\n\r", bchars, 42);

The result:

The rain in Spain falls mainly on the

plain.


WriteComponentResFile procedure
WriteComponentResFile

See also

Writes components and their properties to a file using a Windows resource file format.

Unit

Classes

Category

streaming utilities

extern PACKAGE void __fastcall WriteComponentResFile(const System::AnsiString FileName, TComponent* Instance);

Description

Use WriteComponentResFile to save the component specified by the Instance parameter to the specified file, storing it in a Windows resource-file format.

To read a component written with WriteComponentResFile, call ReadComponentResFile.


Active, CommonAVI example

To run this example, create a new project, place a button on the form, and insert the example code to the button click event. Place the button on the bottom of the form to leave room for the TAnimate component that will be created on the fly.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TForm *TempForm = new TForm(this);

  TAnimate *pAnimate = new TAnimate(TempForm);

  pAnimate->Parent = TempForm;

  pAnimate->CommonAVI = aviFindFile;

  pAnimate->Active = true;

  TempForm->Show();

  // Simulate a lengthy process.  Alter this value

  // to accomodate your machine speed.

  for (int i = 0; i < 900000; i++)

   Application->ProcessMessages();

  delete TempForm;

}


Assign, Dormant, FreeImage, Monochrome, ReleaseHandle example
Assign, Dormant, FreeImage, Monochrome, ReleaseHandle, LoadFromFile example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Graphics::TBitmap *Bitmap1 = new Graphics::TBitmap();

  Graphics::TBitmap *Bitmap2 = new Graphics::TBitmap();

  try

  {

    Bitmap1->LoadFromFile("C:\Program Files\Borland\CBuilder\Images\Splash\256color\factory.bmp ");

    Bitmap2->Assign(Bitmap1);     // Copy Bitmap1 into Bitmap2

    Bitmap2->Dormant();           // Free up GDI resources

    Bitmap2->FreeImage();         // Free up Memory.

    Canvas->Draw(20,20,Bitmap2);  // Note that previous calls don't lose the image

    Bitmap2->Monochrome = true;

    Canvas->Draw(80,80,Bitmap2);

    Bitmap2->ReleaseHandle();       // This will actually lose the bitmap;

  }

  catch (...)

  {

    MessageBeep(0);

  }

  delete Bitmap1;

  delete Bitmap2;

}


TBitmap::LoadFromClipboard example
TBitmap::LoadFromClipboardFormat example

The following code draws a bitmap image from the Clipboard when a button is pressed.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TClipboard *pCB = Clipboard();

  if (pCB->HasFormat(CF_BITMAP))

  {

    Graphics::TBitmap *pBitmap = new Graphics::TBitmap();

    try

    {

      pBitmap->LoadFromClipboardFormat(CF_BITMAP, pCB->GetAsHandle(CF_BITMAP), 0);

      Canvas->Draw(5,5,pBitmap);

    }

    catch (...)

    {

      MessageBeep(0);

    }

    delete pBitmap;

  }

  else

    MessageBeep(0);

}


TBitmap::LoadFromResourceName example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Graphics::TBitmap *Bitmap1 = new Graphics::TBitmap();

  try

  {

    Bitmap1->LoadFromResourceName(HInstance, "THEBITMAP");

    Canvas->Draw(12,12,Bitmap1);

  }

  catch (...)

  {

    MessageBeep(0);

  }

  delete Bitmap1;

}


SaveToClipboardFormat, SetAsHandle example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int DataHandle;

  HPALETTE APalette;

  unsigned short MyFormat;

  Graphics::TBitmap *Bitmap = new Graphics::TBitmap();

  try

  {

    Bitmap->LoadFromFile("C:\Program  Files\Borland\CBuilder\Images\Splash\256color\factory.bmp ");

    // generate a clipboard format, with data and palette

    Bitmap->SaveToClipboardFormat(MyFormat,DataHandle,APalette);

    // save the data to the clipboard using that format and

    // the generated data

    Clipboard()->SetAsHandle(MyFormat,DataHandle);

  }

  catch (...)

  {

     ShowMessage("Failed to copy image to clipboard!");

  }

  delete Bitmap;


ScanLine, Height example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Graphics::TBitmap *pBitmap = new Graphics::TBitmap();

// This example shows drawing directly to the Bitmap

  Byte *ptr;

  try

  {

    pBitmap->LoadFromFile("C:\Program Files\Borland\CBuilder\Images\Splash\256color\factory.bmp ");

    for (int y = 0; y < pBitmap->Height; y++)

    {

      ptr = pBitmap->ScanLine[y];

      for (int x = 0; x < pBitmap->Width; x++)

        ptr[x] = (Byte)y;

    }

    Canvas->Draw(0,0,pBitmap);

  }

  catch (...)

  {

    ShowMessage("Could not load or alter bitmap");

  }

  delete pBitmap;

}


Canvas, Transparent, TransparentMode, TransparentColor example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Graphics::TBitmap *pBitmap = new Graphics::TBitmap();

  try

  {

    pBitmap->LoadFromFile("C:\Program Files\Borland\CBuilder\Images\Splash\256color\factory.bmp ");

    pBitmap->Transparent = true;

    pBitmap->TransparentColor = pBitmap->Canvas->Pixels[50,50];

    Form1->Canvas->Draw(0,0,pBitmap);

    pBitmap->TransparentMode = tmAuto;

    // Transparent color now is clDefault = 0x20000000;

    Form1->Canvas->Draw(50,50,pBitmap);

  }

  catch (...)

  {

    ShowMessage("Could not load or display bitmap");

  }

  delete pBitmap;

}


Bands, Items, Text example

To run this example, add the example code to a new project. The example code dynamically creates a TCoolbar and three TCoolBand objects populated with a windowed control in each TCoolBand.

void AddBands(CoolBar: TCoolBar, TList *Objects)

{

  TControl *pCurrent;

  for (int i = 0; i < Objects->Count; i++)

  {

    pCurrent = (TControl *)Objects->Items[i];

    // only add windowed controls to the coolbar

    if (dynamic_cast<TWinControl *>(pCurrent) != NULL)

    {

      // Placing the control onto the CoolBar

      // causes the TCoolBar object to create a TCoolBand

      // and place the control within the band.

      pCurrent->Parent = Coolbar;

      // Get the reference of the TCoolBand just created and assign text.

      CoolBar->Bands->Items[CoolBar->Bands->Count - 1]->Text =

          pCurrent->ClassName;

    }

  }

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TCoolBar *pCoolBar = new TCoolBar(this);

  TList *pList;

  pCoolBar->Parent = this;

  CoolBar->Align = alTop;

  pList = new TList();

  try

  {

    TControl *pControl;

    pControl = new TButton(CoolBar);

    pList->Add(pControl);

    pControl = new TCheckBox(CoolBar);

    pList->Add(pControl);

    pControl = new TEdit(CoolBar);

    pList->Add(pControl);

    AddBands(CoolBar, pList);

  }

  catch (...)

  {

    ShowMessage("Some objects could not be added to Coolband");

  }

  delete pList;

}


HeaderSection, OnDrawSection, Sections, Canvas, TextOut example

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  THeaderSection *pSection;

  for (int i = 0; i <= 4; i++)

  {

    pSection = HeaderControl1->Sections->Add();

    pSection->Text = "Section " + IntToStr(i);

    pSection->MinWidth = pSection->Text.Length * HeaderControl1->Font->Size;

    // Owner draw every other section

    if (i % 2 == 0)

      pSection->Style = hsOwnerDraw;

    else

      pSection->Style = hsText;

  }

}

void __fastcall TForm1::HeaderControl1DrawSection(THeaderControl *HeaderControl, THeaderSection *Section, const TRect &Rect, bool Pressed)

{

  if (Pressed)

    HeaderControl->Canvas->Font->Color = clRed;

  else

    HeaderControl->Canvas->Font->Color = clBlue;

  HeaderControl->Canvas->TextOut(Rect.Left + HeaderControl->Canvas->Font->Size, Rect.Top + 2, "Custom " + IntToStr(Section->Index));

}


HotKey example

To use this example, create a form with a main menu component and a HotKey component.  At design time, use the Menu designer to add menu items, including a "File" menu with subitems that includes a "New" menu item.  Add the following code to the OnCreate method of the form and the OnClick event of the File menu item.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  // Default to "Ctrl + A"

  HotKey1->Modifiers.Clear();

  HotKey1->Modifiers << hkCtrl;

  // Don't allow shift or alt

  HotKey1->InvalidKeys.Clear();

  HotKey1->InvalidKeys << hcShift << hcAlt;

  HotKey1->Visible = false;

}

void __fastcall TForm1::File1Click(TObject *Sender)

{

  // Assign hotkey to the menu's File "New" item.

  New1->ShortCut = HotKey1->HotKey;

}


Columns, Caption, Items, SubItems, Add example

This example requires only a blank form.  All other objects: TListView, TListColumns, TListItems, are created dynamically.  You must add #include <comctrls.hpp> to the top of the unit file.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  const char Names[6][2][10] =

   {{"Rubble","Barny"},

    {"Michael", "Johnson"},

    {"Bunny", "Bugs"},

    {"Silver", "HiHo"},

    {"Simpson", "Bart"},

    {"Squirrel", "Rockey"}};

  TListColumn  *NewColumn;

  TListItem  *ListItem;

  TListView   *ListView = new TListView(this);

  ListView->Parent = this;

  ListView->Align = alClient;

  ListView->ViewStyle = vsReport;

  NewColumn = ListView->Columns->Add();

  NewColumn->Caption = "Last";

  NewColumn = ListView->Columns->Add();

  NewColumn->Caption = "First";

  for (int i = 0; i < 6; i++)

  {

    ListItem = ListView->Items->Add();

    ListItem->Caption = Names[i][0];

    ListItem->SubItems->Add(Names[i][1]);

  }

}


Column, Items, ViewStyle, SmallImages, LargeImages, ImageIndex, AddObject, Objects example

This example requires a TListView, an TImageList and a TComboBox. You will need to double click the image list and add several images to the image list prior to running the project. You can use *.bmp or *.ico files from the \Images\Icons directory.

During the form OnCreate event handler, items for the List View control are created for each image in the Image List and the ImageIndex is assigned the number of the image within the ImageList.  Two columns are created so that when ViewStyle is vsReport, you will have columns to view.

Also within the forms OnCreate event handler assign the ComboBox each of the four TViewStyle constants. to the Items Objects property. You could also simply code this, for example within a series of OnClick event handlers as, for instance, ListView1.ViewStyle := vsIcon.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TListItem *pItem;

  TListColumn *pColumn;

  // Create a ListView item for each image in the ImageList

  ListView1->SmallImages = ListView1->LargeImages = ImageList1;

  for (int i = 0; i < ImageList1->Count; i++)

  {

    pItem = ListView1->Items->Add();

    pItem->Caption = "Image" + IntToStr(i);

    pItem->ImageIndex = i;

  }

  // Create two columns to show during viewing as vsReport

  pColumn = ListView1->Columns->Add();

  pColumn->Caption = "Column 1";

  pColumn = ListView1->Columns->Add();

  pColumn->Caption = "Column 2";

  // Add View styles and constants to the Combo Box

  ComboBox1->Items->AddObject("vsIcon", (TObject *)vsIcon);

  ComboBox1->Items->AddObject("vsList", (TObject *)vsList);

  ComboBox1->Items->AddObject("vsReport", (TObject *)vsReport);

  ComboBox1->Items->AddObject("vsSmallIcon", (TObject *)vsSmallIcon);

  // Display first item in the Combo Box

  ComboBox1->ItemIndex = 0;

}

void __fastcall TForm1::ComboBox1Click(TObject *Sender)

{

  ListView1->ViewStyle = (TViewStyle) ComboBox1->Items->Objects[ComboBox1->ItemIndex];

}


Open, VisibleButtons, Shareable example

MediaPlayer1->Filename = "c:\win95\roaring.wav"; //specify sound file

MediaPlayer1->ShowHint = true; //show buttons hints

MediaPlayer1->Shareable = true; //allow others to use the same .wav file

MediaPlayer1->VisibleButtons.Clear();

MediaPlayer1->VisibleButtons << btPlay << btStop; //limit to just two buttons

MediaPlayer1->Open(); //play it


DeviceType, Display, Open, Play example

char sWinDir[255];

GetWindowsDirectory(sWinDir, sizeof(sWinDir));

MediaPlayer1->Filename = AnsiString(sWinDir) + "\Clock.avi"; //specify video file

MediaPlayer1->DeviceType = dtAVIVideo; //set Device compatibility to AVI

MediaPlayer1->Display = Panel1; //Set display device to a TPanel

MediaPlayer1->Open();

MediaPlayer1->Play();


ActivePage, PageCount, OnChange example

This project requires a TPageControl already on the form. Also, you must add pages to the TPageControl by right clicking and selecting New Page.

The example code will allow the user to select the ActivePage property through selection of a ComboBox item.  During the form create, the Combo Box control is loaded with the names of each of the tabs, as well as the instance pointers to the corrosponding tab.  When the user selects the Combo Box item, the associated TTabSheet object contained in the Combo Box Objects array is used to set the ActivePage property.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < PageControl1->PageCount; i++)

  {

    ComboBox1->Items->AddObject(PageControl1->Pages[i]->Name, PageControl1->Pages[i]);

    ComboBox1->ItemIndex = 0;

  }

}

void __fastcall TForm1::ComboBox1Change(TObject *Sender)

{

  TComboBox *pCB = dynamic_cast<TComboBox *>(Sender);

  if (pCB)

    PageControl1->ActivePage = (TTabSheet *)(pCB->Items->Objects[pCB->ItemIndex]);

}


PageControl, FindNextPage, OnChange example

This project requires a new TPageControl, as-is, with no new pages created at design time.

The form OnCreate event handler adds several new TabSheet controls to the Page Control.  The Page Control’s OnChange event handler displays a message dialog when the user changes tabs.  The message dialog contains the captions for the tabs immediately before and after the active tab.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < 10; i++)

  {

    TTabSheet *pPage = new TTabSheet(PageControl1);

    pPage->PageControl = PageControl1;

    pPage->Caption = AnsiString("Page") + IntToStr(i);

    pPage->Name = AnsiString("ts") + pPage->Caption;

  }

}

void __fastcall TForm1::PageControl1Change(TObject *Sender)

{

  AnsiString PrevCaption, NextCaption;

  TPageControl *pPC = (TPageControl *)Sender;

  PrevCaption = pPC->FindNextPage(pPC->ActivePage, true, false)->Caption;

  NextCaption = pPC->FindNextPage(pPC->ActivePage, false, false)->Caption;

  ShowMessage(AnsiString("Previous tab caption: '") + PrevCaption + AnsiString("'  Next tab Caption: '") + NextCaption + AnsiString("'"));

}


MultiLine, Checked example

This project requires a PageControl with no pages created, and a TCheckBox. During the form create, a series of tabs will be created on the Page Control that exceed the Page Control's width.  When the Check Box control is clicked, the setting of the MultiLine property is toggled, alternately stacking the tabs vertically, or along a single line horizontally.

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

  PageControl1->MultiLine = CheckBox1->Checked;

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Checkbox1->Caption = "Stack Tabs?";

  for (int i = 0; i < 20; i++)

  {

    TTabSheet *pPage = new TTabSheet(PageControl1);

    pPage->PageControl = PageControl1;

    pPage->Caption = AnsiString("Page") + IntToStr(i);

  }

}


OnChange, OnShow example

This project requires a Page Control.  You will need to  populate the Page Control by right clicking and selecting New Page from the context menu. As the tabs are selected by the user, the Page Control OnChange event fires which causes the form caption to display the captions of each of the TTabSheets attached to the Page Control.

Note the use of the Form’s OnShow event handler to set the caption when the form first appears, before any changes trigger the OnChange event of the Page Control.

void __fastcall TForm1::PageControl1Change(TObject *Sender)

{

  Caption = AnsiString("Now working on tab: " + PageControl1->ActivePage->Caption;

}

void __fastcall TForm1::FormShow(TObject *Sender)

{

  PageControl1Change(Sender);

}


OnChanging example

This project requires a TPageControl, several TTabSheets (to add sheets, right click the Page Control and select "New Page" from the context menu), and a TEdit control on the first tab sheet.

The user is not allowed to change to a new page if the active page is "TabSheet1" and there is no text in the Edit Control.

void __fastcall TForm1::PageControl1Changing(TObject *Sender, bool &AllowChange)

{

  if (((TPageControl *)Sender)->ActivePage == TabSheet1)

    AllowChange = (!Edit1->Text.IsEmpty());

  else

    AllowChange = true;

  if (AllowChange == false)

  {

    MessageBeep(0);

    Edit1->SetFocus();

  }

}


OnCreate, OnClick, SelectNextPage example

This example requires a new TPageControl, as-is, with no new pages created at design time, and a TUpDown control, also from the Win95 page of the component palette.

The form OnCreate event handler adds several new TabSheet controls to the Page Control.

The UpDown1Click event handler fires when the user clicks the up or down button on the TUpDown control.  The SelectNextPage method of the Page Control goes forward the comparison (Button = btNext) evaluates as true.  If Button is not btNext, the previous Tab Page is selected.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < 10; i++)

  {

    TTabSheet *pPage = new TTabSheet(PageControl1);

    pPage->PageControl = PageControl1;

    pPage->Caption = AnsiString("Page") + IntToStr(i);

  }

}

void __fastcall TForm1::UpDown1Click(TObject *Sender, TUDBtnType Button)

{

  PageControl1->SelectNextPage(Button == btNext);

}


Pages, TabHeight, TabWidth, TextHeight, TextWidth example

This project requires a TPageControl and several TTabPages. To add new pages, right click the TPageControl and select "New Page".

During the form creation the width and height of all tabs on the Page Control becomes double the largest previous value.  So if there are three tabs with captions that are 12, 23 and 19 characters long, the TabWidth would be the number of pixels required to fit 46 characters.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < PageControl1->PageCount; i++)

  {

     AnsiString s = PageControl1->Pages[i]->Caption;

     if (Canvas->TextWidth(s) * 2 > PageControl1->TabWidth)

        PageControl1->TabWidth = Canvas->TextWidth(s) * 2;

      if (Canvas.TextHeight(s) * 2 > PageControl1->TabHeight)

        PageControl1->TabHeight = Canvas->TextHeight(s) * 2;

  }

}


Align example

// dynamically create a TProgressBar control

// and align it to the bottom of the form.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TProgressBar *ProgressBar = new TProgressBar(this);

  ProgressBar->Parent = this;

  ProgressBar->Align = alBottom;

}


Min, Max, Position, RecordCount, First, Next example
Min, Max, Position RecordCount, First, Next example

// Read through all records in a table and update

// the ProgressBar accordingly.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ProgressBar1->Min = 0;

  ProgressBar1->Max = Table1->RecordCount;

  Table1->First();

  for (int i = ProgressBar1->Min; i <= ProgressBar1->Max; i++)

  {

    ProgressBar1->Position = i;

    Table1->Next();

    // do something with record...

  }

}


Step, StepIt example

This example reads bytes from a file in tenths of the size of the file. The ProgressBar displays the status of each  1/10th step as it's read into the buffer.

The example assumes a TButton and a TProgressBar control already placed on the form.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  FILE *F;

  F = fopen("c:\autoexec.bat", "r");

  if (F)

  {

    struct stat statbuf;

    fstat(fileno(F), &statbuf);

    ProgressBar1->Max = statbuf.st_size;

    if (ProgressBar1->Max > 10)

      ProgressBar1->Step = (ProgressBar1->Max)/10;

    else

      ProgressBar1->Step = ProgressBar1->Max;

    char *DataBuffer = new char[ProgressBar1->Step];

    for (ProgressBar1->Position = 0;

         ProgressBar1->Postion < ProgressBar1->Max;

         ProgressBar1->StepIt())

    {

      fread(DataBuffer, ProgressBar1->Step, 1, F);

      // do something with the next chunk

    }

    delete DataBuffer;

    fclose(F);

  }

}


StepBy, CreateForm, Run, Show, Update, Initialize example

This example shows progress of loading forms as an application starts up. The code example is placed in the project source (*.dpr) file.  To see project source, select the View | Project Source menu item.

You will need to set up your project with the following steps before using the code example:

•	Add four additional forms to a default project.

•	Place a TProgressBar on Form5

•	Take the  Project | Options | Forms menu option and place Form5 on the available forms list.

•	Change the code of your project (*.dpr) file to look like the example.

#include <vcl\vcl.h>

#include "Unit5.h"

#pragma hdrstop

//---------------------------------------------------------------------------

USEFORM("Unit1.cpp", Form1);

USERES("Project1.res");

USEFORM("Unit2.cpp", Form2);

USEFORM("Unit3.cpp", Form3);

USEFORM("Unit4.cpp", Form4);

USEFORM("Unit5.cpp", Form5);

//---------------------------------------------------------------------------

WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)

{

  try

  {

    Application->Initialize();

    Application->CreateForm(__classid(TForm5), &Form5);

    Form5->ProgressBar1->Max = 100;

    Form5->Show();   // show a splash screen contain ProgressBar control

    Form5->Update(); // force display of Form5

    Application->CreateForm(__classid(TForm1), &Form1);

    Form5->ProgressBar1->StepBy(25);

    Application->CreateForm(__classid(TForm2), &Form2);

    Form5->ProgressBar1->StepBy(25);

    Application->CreateForm(__classid(TForm3), &Form3);

    Form5->ProgressBar1->StepBy(25);

    Application->CreateForm(__classid(TForm4), &Form4);

    	Form5->ProgressBar1->StepBy(25);

    delete Form5;

    Application->Run();

  }

  catch (Exception &exception)

  {

    Application->ShowException(&exception);

  }

  return 0;

}


TParaAttributes::Alignment example

To use this example, place a Toolbar and a RichEdit on the form. Right click the toolbar and select New Button three times.  Place the ToolButton1Click handling code in the on click event of the first TToolButton, then attach the same OnClick handler for each button.

void __fastcall TForm1::ToolButton1Click(TObject *Sender)

{

  if (Sender == ToolButton1)

    RichEdit1->Paragraph->Alignment = taLeftJustify;

  else if (Sender == Toolbutton2)

    RichEdit1->Paragraph->Alignment = taCenter;

  else if (Sender == Toolbutton3)

    RichEdit1->Paragraph->Alignment = taRightJustify;

}


SimplePanel, SimpleText, Add example

This example requires no additional controls.  All controls are created dynamically within the form's OnCreate event handler.

Note: Be sure to add #inlcude <comctrls.hpp>  to your unit to support TRichEdit.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TStatusBar *pStatus = new TStatusBar(this);

  // Display the StatusBar control on the surface

  // of the form.

  pStatus->Parent = this;

  // Allow a single line of text -- no panels.

  PStatus->SimplePanel = true;

  // Provide sample text.

  // Create a new instance of TRichEdit, set it's

  // properties, and display on the form.

  TRichEdit *pRich = new TRichEdit(this);

  // Display the RichEdit control on the surface

  // of the form.

  pRich->Parent = this;

  // The RichText control takes all space left

  // over from the StatusBar.

  pRich->Align = alClient;

  // Add 50 lines to the RichText

  for (int i = 1; i <= 50; i++)

    pRich->Lines->Add(AnsiString("This is line ") + IntToStr(i));

  pRich->SelStart = 0; // set text cursor to first character

  pStatus->SimpleText = IntToStr(pRich->Lines->Count) + " Lines loaded";

}


DefAttributes, SelAttributes, Color, Height, Style example

This example requires a TRichEdit and a TButton. Leave the default text, usually "RichEdit1", in the lines property. The DefAttributes will apply to this text.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  RichEdit1->DefAttributes->Color = clBlue;

  RichEdit1->DefAttributes->Style =

    RichEdit1->DefAttributes->Style << fsBold << fsItalic;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  RichEdit1->SelAttributes->Color = clRed;

  RichEdit1->SelAttributes->Height += 5;

  RichEdit1->Lines->Add("This line of text will be red. ");

}


Position, Execute, FindText, OnFind, SelStart, SelLength example

This example requires a TRichEdit, a TButton, and a TFindDialog.

Clicking the button click will display a Find Dialog to the right of the edit control.  Filling in the "Find what" text and pressing the Find Next button will select the first matching string in the Rich Edit control that follows the previous selection.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  FindDialog1->Position = Point(RichEdit1->Left + RichEdit1->Width, RichEdit1->Top);

  FindDialog1->Execute();

}

void __fastcall TForm1::FindDialog1Find(TObject *Sender)

{

  int FoundAt, StartPos, ToEnd;

  // begin the search after the current selection

  // if there is one

  // otherwise, begin at the start of the text

  if (RichEdit1->SelLength)

    StartPos = RichEdit1->SelStart + RichEdit1->SelLength;

  else

    StartPos = 0;

  // ToEnd is the length from StartPos

  // to the end of the text in the rich edit control

  ToEnd = RichEdit1->Text.Length() - StartPos;

  FoundAt = RichEdit1->FindText(FindDialog1->FindText, StartPos, ToEnd, TSearchTypes()<< stMatchCase);

  if (FoundAt != -1)

  {

    RichEdit1->SetFocus();

    RichEdit1->SelStart = FoundAt;

    RichEdit1->SelLength = FindDialog1->FindText.Length();

  }

}


Font, Name, Fonts, ItemIndex example

To use this example, place a TComboBox and TRichEdit on a form.

During form creation, a list of font names are loaded into the combo box. When the combo box is clicked, the Rich Edit control font is set to the corrosponding font name in the combo box.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < Screen->Fonts->Count; i++)

   ComboBox1->Items->Add(Screen->Fonts->Strings[i]);

}

void __fastcall TForm1::ComboBox1Click(TObject *Sender)

{

  RichEdit1->Font->Name = ComboBox1->Items->Strings[ComboBox1->ItemIndex];

}


HideSelection example
HideSelection, Height example

This example needs only a blank form.  Three Rich Edit controls are placed vertically on the form, each contain a line of text, and the second form has HideSelection set to false.

Try tabbing between the three Rich Edit controls and observe the effect on the selected text.

#include <ComCtrls.hpp>

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int I = 0; I <= 2; I++)

  {

    TRichEdit *pRich = new TRichEdit(this);

    pRich->Parent = this;

    pRich->Top = pRich->Height * I;

    pRich->Text = "This text will take the focus.";

    pRich->SelStart = 0;

    pRich->SelLength = pRich->Text.Length();

    if (I == 1)

      pRich->HideSelection = false;

  }

}


OnSelectionChange example

This example requires a TStatusBar and a TRichEdit.  The code within the form's OnCreate will take care of sizing the Rich Edit and setting the OnSelectionChange event to be handled by RichEdit1SelectionChange (or you can paste the code directly into the OnSelectionChange event handler.)

As you type in the Rich Edit control, the current character location the selection begin and end will display in the status bar control.

void __fastcall TForm1::RichEdit1SelectionChange(TObject *Sender)

{

  StatusBar1->SimpleText = AnsiString("Selection Start: ") + IntToStr(SelStart) + AnsiString("  Selection End: ") + IntToStr(SelStart + SelLength);

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  RichEdit1->Align = alClient;

  RichEdit1->OnSelectionChange = RichEdit1SelectionChange;

  StatusBar1->SimplePanel = true;

}


Lines, Paragraph, FirstIndent, Numbering example

This example requires only a form.

A Rich Edit control is created on the form and aligned to take the entire client area of the form.  A series of lines are written to the Rich Edit control's Lines property, and the Paragraph property manipulated such that the first items displayed are bulletted, a second group of lines are un-bulletted and centered, and the last group is left justified and indented.

#include <ComCtrls.hpp>;

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TRichEdit *pRich = new TRichEdit(this);

  pRich->Parent = this;

  pRich->Align = alClient;

  pRich->Lines->Clear();

  // set numbering style

  pRich->Paragraph->Numbering = nsBullet;

  pRich->Lines->Add("Introduction");

  pRich->Lines->Add("New members to our team");

  pRich->Lines->Add("New Budget discussion");

  pRich->Lines->Add("Facilities");

  pRich->Lines->Add("Q & A");

  pRich->Paragraph->Numbering = nsNone;

  pRich->Paragraph->Alignment = taCenter;

  pRich->Lines->Add("");

  pRich->Lines->Add("Suggested Topics: ");

  pRich->Lines->Add("");

  pRich->Paragraph->Alignment = taLeftJustify;

  pRich->Paragraph->FirstIndent = 10;

  pRich->Lines->Add("");

  pRich->Lines->Add("Parking lot repair");

  pRich->Lines->Add("Cost overruns");

}


PlainText, LoadFromFile example

This example requires two TRichEdit controls placed on the form.

When the form becomes visible, the first Rich Edit control will display the rich text in it's raw form, including formatting characters. The second will show the rich text in it's intended format.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

// you may need to change this path to suit your environment

  char const *Path = "C:\Program Files\Borland\CBuilder\Examples\APPS\RICHEDIT\OVERVIEW.RTF";

  RichEdit1->PlainText = true;

  RichEdit1->Lines->LoadFromFile(Path);

  RichEdit2->PlainText = false;

  RichEdit2->Lines->LoadFromFile(Path);

}


Print example

void __fastcall TForm1::FormCreate(TObject *Sender)

{

// you may need to change this path to suit your environment

  char const *Path = "C:\Program Files\Borland\CBuilder\Examples\APPS\RICHEDIT\OVERVIEW.RTF";

  RichEdit2->Lines->LoadFromFile(Path);

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

// The parameter string shows in the print queue under "Document   // name".

  RichEdit1->Print(Form1->Caption);

}


HideScrollBars, ScrollBars example

This example requires: TRichEdit, TRadioGroup, TCheckBox, TButton. Clicking the Radio Group control sets the ScrollBar style of the RichEdit. Toggling the Check Box turns HideScrollBars on and off.  Clicking the button loads the Rich Edit with a large amount of contiguous text.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  RichEdit1->Lines->Clear();

  for (int i = 0; i < 500; i++)

    RichEdit1->Text = RichEdit1->Text + AnsiString("This is sentance ") + IntToStr(i) + ".  ";

  RichEdit1->SelStart = 0; // move text cursor to top of edit

}

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

  RichEdit1->HideScrollbars = CheckBox1->Checked;

}

void __fastcall TForm1::RadioGroup1Click(TObject *Sender)

{

  TScrollStyle ScrollBarA[4] = {ssBoth, ssHorizontal, ssNone, ssVertical };

  RichEdit1->ScrollBars = ScrollBarA[RadioGroup1->ItemIndex];

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  RadioGroup1->Caption = "Scroll Bars";

  RadioGroup1->Items->Clear();

  RadioGroup1->Items->Add("ssBoth");

  RadioGroup1->Items->Add("ssHorizontal");

  RadioGroup1->Items->Add("ssNone");

  RadioGroup1->Items->Add("ssVertical");

  CheckBox1->Caption = "Hide Scroll Bars";

  CheckBox1->Checked = true;

  Button1->Caption = "Load Text";

}


TStrings::Assign, TStrings::Add example

TStrings StringList = new TStringList();

try

{

  StringList->Add("This example uses A string List. ");

  StringList->Add("It is the easiest way to add strings");

  StringList->Add("to a combobox's list of strings. ");

  StringList->Add("Always remember TStrings is abstract,");

  StringList->Add("So create a TStringList instead.");

  ComboBox1->Width = 210;

  ComboBox1->Items->Assign(StringList);

  ComboBox1->ItemIndex = 0;

}

catch (...)

{

  delete StringList;

  throw;

}

delete StringList;


TTabSheet::Caption example

This example requires a TPageControl, a TEdit and a TButton. When the button is clicked, the caption of the active tab changes to that of the TEdit.

These lines of code could also be written :

PageControl1->ActivePage->Caption = Edit1->Text;

This would obviate the need for a TTabSheet variable since PageControl.ActivePage is already of type TTabSheet.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TTabSheet pSheet = PageControl1->ActivePage;

  pSheet->Caption = Edit1->Text;

}


PageIndex, TabIndex, TabVisible example

This example creates ten Tab Sheets and sets the captions to display PageIndex and TabIndex for each tab.  Odd numbered tabs have their TabVisible property set off to demonstrate the effect on PageIndex vs TabIndex.  On the series of visible tabs, PageIndex will read 0, 2, 4, 6, 8, and TabIndex will read 0, 1, 2, 3, 4.  PageIndex counts only visible tabs.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  PageControl1->MultiLine = true;

  for (int i = 0; i < 10; i++)

  {

    TTabSheet *pPage = new TTabSheet(this);

    pPage->PageControl = PageControl1;

    pPage->TabVisible = (i % 2 == 0);

    pPage->Caption = AnsiString("PageIndex: ") + IntToStr(pPage->PageIndex) + AnsiString("  TabIndex: ") + IntToStr(pPage->TabIndex);

  }

}


Visible, OnClick example

This examples requires a TPageControl and a TCheckBox.  The form OnCreate event handler populates each sheet with an edit control placed somewhere on the client area of the sheet.

Clicking the checkbox will cause the client area (not the tab area) of the Tab Control to become invisible when the Check Box is unchecked.

void __fastcall TForm1::PageControl1Change(TObject *Sender)

{

  CheckBox1->Checked = PageControl1->ActivePage->Visible;

}

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

  PageControl1->ActivePage->Visible = CheckBox1->Checked;

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < 10; i++)

  {

    TTabSheet *pPage = new TTabSheet(this);

    pPage->PageControl = PageControl1;

    pPage->Caption = AnsiString("Page") + IntToStr(i);

    TEdit *pEdit = new TEdit(this);

    pEdit->Parent = pPage;

    pEdit->Left = random(pPage->ClientWidth - pEdit->Width);

    pEdit->Top = random(pPage->ClientHeight - pEdit->Height);

  }

  PageControl1Change(Sender);

}


TToolButton, TToolBar example

To use this example, create a new application and add the example code to the unit.

#include <comctrls.hpp>

void AddButtons(TToolBar *pToolBar, TStringList *pCaptions)

{

  for (int i = 0; i < pCaptions->Count; i++)

  {

    TToolButton *pButton = new TToolButton(pToolBar);

    pButton->Parent = pToolBar;

    pButton->Caption = pCaptions->Strings[i];

    if (pButton->Caption == "|")

      pButton->Style = tbsSeparator;

    else

      pButton->Style = tbsButton;

  }

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TToolBar *pToolBar = new TToolBar(this);

  pToolBar->Parent = this;

  TStringList *pCaptions = new TStringList();

  pCaptions->Add("New");

  pCaptions->Add("Save");

  pCaptions->Add("|");

  pCaptions->Add("Cut");

  pCaptions->Add("Copy");

  pCaptions->Add("Paste");

  AddButtons(pToolBar, pCaptions);

  delete pCaptions;

  pToolBar->ShowCaptions = True;

  pToolBar->Height = 40;

}


OnClose example

This example displays a message dialog box when the user attempts to close the form. If the user clicks the Yes button, the form closes; otherwise, the form only minimizes.

void __fastcall TForm1::FormClose(TObject *Sender, TCloseAction &Action)

{

  if (MessageDlg("Close application ?", mtConfirmation, TMsgDlgButtons() << mbYes << mbNo,0) == mrYes)

    Action = caFree;

  else

    Action = caMinimize;

}


OnCloseQuery example

When the user attempts to close the form in this example, a message dialog appears that asks the user if it is OK to close the form. If the user chooses the OK button, the form closes. If the user chooses Cancel, the form doesn't close.

void __fastcall TForm1::FormCloseQuery(TObject *Sender, bool &CanClose)

{

  if (MessageDlg("Close the form?", mtConfirmation, TMsgDlgButtons() << mbOK << mbCancel,0) == mrCancel)

    CanClose = false;

}


TForm::OnPaint example

The following code loads a background bitmap onto the Canvas of the main form in the OnPaint event handler.  In the header file for Unit 1. add a private member to TForm1 of type Graphics::TBitmap named TheGraphic;

void __fastcall TForm1::FormPaint(TObject *Sender)// OnPaint event handler

{

  Form1->Canvas->Draw(0, 0, TheGraphic); // Draw the graphic on the Canvas

}

void __fastcall TForm1::FormCreate(TObject *Sender)// OnCreate event handler

{

  TheGraphic = new Graphics::TBitmap(); // Create the bitmap object

  TheGraphic->LoadFromFile("C:\APP\BKGRND.BMP"); // Load the bitmap from a file

}


Canvas Example
OnDrawItem, Canvas example

Here is a typical handler for an OnDrawItem event. In the example, a list box with the lbOwnerDrawFixed style draws a bitmap to the left of each string.

void __fastcall TForm1::ListBox1DrawItem(TWinControl *Control, int Index, TRect &Rect, TOwnerDrawState State)

{

  Graphics::TBitmap *pBitmap; // temporary variable for item’s bitmap

  int     Offset = 2;   // default text offset width

  // note that we draw on the listbox’s canvas, not on the form

  TCanvas *pCanvas = ((TListBox *)Control)->Canvas;

  pCanvas->FillRect(Rect); // clear the rectangle

  pBitmap = (Graphics::TBitmap *)((TListBox *)Control)->Items->Objects[Index];

  if (pBitmap)

  {

    pCanvas->BrushCopy(Bounds(Rect.Left + Offset, Rect.Top, pBitmap->Width, pBitmap->Height), pBitmap, Bounds(0, 0, pBitmap->Width, pBitmap->Height), clRed); // render bitmap

    Offset += pBitmap->Width + 4;   // add four pixels between bitmap and text}

  }

  // display the text

  pCanvas->TextOut(Rect.Left + Offset, Rect.Top, ((TListBox *)Control)->Items->Strings[Index]);

}


TopIndex example

The following example uses a list box containing a list of strings, a button, and an edit box on a form. When the user runs the application and clicks the button, the third item in the list becomes the first item, and the index value of that item appears in the edit box. The index value displayed is 2, indicating the third item in the list (the first item in the list has an index value of 0):

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int Number = 1; Number <= 20; Number++)

    ListBox1->Items->Add(AnsiString("Item ") + IntToStr(Number));

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->TopIndex = 2;

  Edit1->Text = IntToStr(ListBox1->TopIndex);

}


OnMeasureItem example

Here is a typical handler for an OnMeasureItem event. The example assumes that a variable owner-draw list box already has bitmaps associated with each of its strings. It sets the height of the item to the height of the associated bitmap if that height is greater than the default height.

void __fastcall TForm1::ListBox1MeasureItem(TWinControl *Control, int Index, int &Height)

{

  TBitmap *pBitmap = (TBitmap *)((TListBox *)Control)->Items->Objects[Index];

  if (Bitmap && Bitmap->Height > Height)

    Height = Bitmap->Height;

}


TTreeView::CustomSort example

This example shows how to use the CustomSort method to order a tree view in case-insensitive alphabetical order (either forward or backward). The application must provide a callback function such as CompareFunc below, which calls the global AnsiStrIComp function to perform the actual comparison.

int __fastcall CompareFunc(TTreeNode *Node1,TTreeNode *Node2, int Reverse)

{

  int GT = AnsiStrIComp(Node1->Text.c_str(), Node2->Text.c_str());

  if (Reverse)

    return -GT;

  return GT;

}

This procedure can then be used as a parameter to CustomSort to sort the nodes of the tree view.  To sort in ascending order, call

TreeView1->CustomSort((CommCtrl::TTVCompare)CompareFunc, 0);

To sort in descending order, call

TreeView1->CustomSort((CommCtrl::TTVCompare)CompareFunc, 1);


GetHitTestInfoAt example

The following code checks a list of htHitTest types and adds the ones that occur when the mouse was pressed while on the tree view.

void __fastcall TForm1::TreeView1MouseDown(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  THitTests MyHitTest = TreeView1->GetHitTestInfoAt(X,Y);

  if (MyHitTest.Contains(htNowhere))

    ListBox1->Items->Add("Nowhere");

  if (MyHitTest.Contains(htOnItem))

    ListBox1->Items->Add("OnItem");

  if (MyHitTest.Contains(htOnButton))

    ListBox1->Items->Add("OnButton");

  if (MyHitTest.Contains(htOnIndent))

    ListBox1->Items->Add("OnIndent");

  if (MyHitTest.Contains(htOnLabel))

    ListBox1->Items->Add("OnLabel");

  if (MyHitTest.Contains(htOnRight))

    ListBox1->Items->Add("OnRight");

  if (MyHitTest.Contains(htAbove))

    ListBox1->Items->Add("Above");

  if (MyHitTest.Contains(htBelow))

    ListBox1->Items->Add("Below");

  if (MyHitTest.Contains(htOnIcon))

    ListBox1->Items->Add("OnIcon");

  if (MyHitTest.Contains(htOnStateIcon))

    ListBox1->Items->Add("OnStateIcon");

  if (MyHitTest.Contains(htToLeft))

    ListBox1->Items->Add("ToLeft");

  if (MyHitTest.Contains(htToRight))

    ListBox1->Items->Add("ToRight");

}


GetNodeAt, MoveTo, Selected example

The following code uses GetNodeAt to add a dragged node as a child of the node under then mouse when it is dropped.

void __fastcall TForm1::TreeView1DragDrop(TObject *Sender, TObject *Source, int X, int Y)

{

  if (Source != (TObject *)TreeView1 || TreeView1->Selected == NULL)

    return;

  THitTests HT = TreeView1->GetHitTestInfoAt(X, Y);

  TNodeAttachMode AttachMode;

  TTreeNode *pItem = TreeView1->GetNodeAt(X, Y);

  if (HT.Contains(htOnItem) || HT.Contains(htOnIcon))

    AttachMode = naAddChild;

  else if (HT.Contains(htNowhere))

    AttachMode = naAdd;

  else if (HT.Contains(htOnIndent))

    AttachMode = naInsert;

  else

    return;

  TreeView1->Selected->MoveTo(pItem, AttachMode);

}


Command example

The following procedure is a WM_COMMAND message handler. It checks the ItemID field of Msg to see if the message was generated by a menu item called MenuThink. If so, it displays a message dialog. When writing message handlers, remember to call the ancestor’s method afterward, if necessary, so Windows can perform default message processing.

MESSAGE void __fastcall TForm1::WMCommand(Messages::TWMCommand &Message)

{

  if (Message->ItemID == MenuThink->Command)

    Application->MessageBox("This is the Think command", "Hmmm", MB_OK);

  else

    TForm::WMCommand(Message);

}


Insert example

This code inserts a menu item after the first item in a menu named FileMenu:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TMenuItem *NewItem = new TMenuItem(FileMenu);

  try

  {

    NewItem->Caption = "Form1";

    FileMenu->Insert(1, NewItem);

  }

  catch (Exception &e)

  {

    delete NewItem;

    throw;

  }

}


Cookies example

The following function checks whether any of the cookies instruct the Web client to use a secure link when sending the cookie on, and if so, returns True:

bool SecureCookies(TWebResponse *Response)

{

  for (int I = 0; I < Response->Cookies->Count; I++)

    if (Response->Cookies->Items[I]->Secure == true)

      return true;

  return false;

}


CustomForms example

The following code adds the name of all forms, dialogs, and property pages on the screen to ListBox1 when Button1 is clicked.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for (int i = 0; i < Screen->CustomFormCount; i++)

    ListBox1->Items->Add(Screen->CustomForms[i]->Name);

}


TScreen::Height, TScreen::Width example

The following code determines the height of all forms on the screen and resizes any that are taller than the screen height.

for (int i = 0; i < Screen->FormCount; i++)

{

  if (Screen->Forms[i]->Height > Screen->Height)

    Forms[i]->Height = Screen->Height;

  if (Screen->Forms[i]->Width > Screen->Width)

    Forms[i]->Width = Screen->Width;

}


TTreeNode::Item example

The following code uses Item to add the labels of all child nodes of the selected node to a list box when a button is clicked.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for (int i = 0; i < TreeView1->Selected->Count; i++)

    ListBox1->Items->Add(TreeView1->Selected->Item[i]->Text);

}


TTreeNode::CustomSort example

This example shows how to use the CustomSort method to order a subtree in case-insensitive alphabetical order (either forward or backward). The callback function CompareFunc below calls the global AnsiStrIComp function to perform the actual comparison.

int __fastcall CompareFunc(TTreeNode *Node1,TTreeNode *Node2, int Reverse)

{

  int GT = AnsiStrIComp(Node1->Text.c_str(), Node2->Text.c_str());

  if (Reverse)

    return -GT;

  return GT;

}

This procedure can then be used as a parameter to CustomSort to sort the nodes of the tree view.  To sort in ascending order, call

TreeNode1->CustomSort((CommCtrl::TTVCompare)CompareFunc, 0);

To sort in descending order, call

TreeNode1->CustomSort((CommCtrl::TTVCompare)CompareFunc, 1);


Hint, OnHint, GetLongHint example

This example uses a status bar, a menu, and an edit box on a form. Include a value for the Hint property for each menu item in the menu. Also, specify a value for the Hint property of the edit box. Align the status bar at the bottom of the form.

Declare the DisplayHint method as a public procedure of the Form:

class TForm1 : public TForm

{

__published: // IDE-managed Components

private: // User declarations

public: // User declarations

  __fastcall TForm1(TComponent* Owner);

  void __fastcall DisplayHint(TObject *Sender);  // add this line

};

Here is the code to add to the unit file.  It provides the implementation of the DisplayHint method and assigns it to the Application in the form’s OnCreate event handler.

void __fastcall TForm1::DisplayHint(TObject *Sender)

{

  StatusBar1->SimpleText = GetLongHint(Application->Hint);

}

// Here is the form’s OnCreate event handler.

// It assign’s the application’s OnHint event handler at runtime

// because the Application is not available in the Object Inspector

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->OnHint = DisplayHint;

}


TScreen::Cursors, TForm::Cursor example

This example shows how to add custom cursors to an application.  It assumes that a custom cursor with the name NewCursor has been added to the resources (.RC file) of the application. The following code makes this cursor available to the application via the constant crMyCursor, and sets it as the global cursor to the application.

const crMyCursor = 5;

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Screen->Cursors[crMyCursor] = LoadCursor(HInstance, 'NewCursor');

  Cursor := crMyCursor;

end;


TScreen::Cursor example

Assignments to the Screen object's cursor property are typically guarded by a try...catch statement to ensure that normal cursor behavior is restored. Note that the original cursor is saved and restored.  This allows cursor changes to be nested without accidentally restoring the cursor to a hard-code value prematurely.

TCursor Save_Cursor = Screen->Cursor;

Screen->Cursor = crHourglass;    // Show hourglass cursor

try

{

  // Do some lengthy operation

}

catch (...)

{

  Screen->Cursor = Save_Cursor; // always restore the cursor

  throw;

}

Screen->Cursor = Save_Cursor;


StartTransaction, ApplyUpdates, Commit, Rollback, CommitUpdates example

The following procedure illustrates how to apply a dataset’s cached updates to a database in response to a button click:

void __fastcall TForm1::ApplyButtonClick(TObject *Sender)

{

  Database1->StartTransaction();

  try

  {

    CustomerQuery->ApplyUpdates(); // try to write the updates to the database

    Database1->Commit(); // on success, commit the changes;

  }

  catch (...)

  {

    Database1->Rollback(); // on failure, undo the changes

    throw; // throw the exception to prevent a call to CommitUpdates!

  }

  CustomerQuery->CommitUpdates(); // on success, clear the cache

}


UpdateRecordTypes, RevertRecord example

With minor coding, UpdateRecordTypes and RevertRecord can be used to undelete records when cached updates are enabled, as the following procedure demonstrates:

void UndeleteAll(TBDEDataSet *DataSet)

{

  // make only deleted records visible:

  DataSet->UpdateRecordTypes.Clear();

  DataSet->UpdateRecordTypes << rtDeleted;

  try

  {

    for (DataSet->First(); !DataSet->Eof; DataSet->Next())

      DataSet->RevertRecord(); // undelete the current record

  }

  catch (..)

  {

    DataSet->UpdateRecordTypes.Clear();

    DataSet->UpdateRecordTypes << rtModified << rtInserted << rtUnmodified;

    throw;

  }

  DataSet->UpdateRecordTypes.Clear();

  DataSet->UpdateRecordTypes << rtModified << rtInserted << rtUnmodified;

}


DataSetCount, DataSets example

The following code fragment illustrates how DataSets and DataSetCount can be used to ensure that an action is taken for every open dataset that is a table:

for (int i = 0; i < Database1->DataSetCount; i++)

  if (Database1->DataSets[i]->ClassNameIs("TTable"))

    DataSets[i]->CachedUpdates = true;


DatabaseCount, Databases example

The following code sets the KeepConnection property of each active database in the default session to true:

if (Session->DatabaseCount > 0)

  for (int i = 0; i < Session->DatabaseCount; i++)

    Session->Databases[i]->KeepConnection = true;


AddAlias example

This example creates an alias for an InterBase database server:

TStringList MyList = new TStringList();

try

{

  MyList = TStringList.Create();

  MyList->Add("SERVER NAME=IB_SERVER:/PATH/DATABASE.GDB");

  MyList->Add("USER NAME=MYNAME");

  Session1->AddAlias("NewIBAlias", "INTRBASE", MyList);

}

catch(...)

{

  delete MyList;

  throw;

}

delete MyList;


Data, DataRequest, OnDataRequest example

This example shows how to use the OnDataRequest event to allow a client application to pass a filter expression to the provider and then receive only the records matching the filter.

The OnDataRequest event handler of the provider looks like the following:

OleVariant __fastcall TForm1::Provider1DataRequest(TObject *Sender, OleVariant Input)

{

  ((TProvider *)Sender)->DataSet->Filter = (AnsiString)Input;

  ((TProvider *)Sender)->DataSet->Filtered = true;

  ((TProvider *)Sender)->Reset(true);

  return ((TProvider *)Sender)->Data;

}

On the client side, the IProvider interface can be used to fetch the data.  The DataRequest method triggers an OnDataRequest event in the Provider component and returns the result of the event handler:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ClientDataSet1->Data = ClientDataSet1->Provider->DataRequest((OleVariant)FilterEdit->Text);

}


DataSet, OnGetData example

This example shows how to use a provider to encrypt the contents of a field containing sensitive data before it is sent on to the client. The client application must decrypt the data in the OnGetText routine of the SensitiveData field or some other appropriate place.

/* this is the OnGetData event handler for the provider in the DBClientTest remote data module. */

void __fastcall TDBClientTest::ProviderGetData(TClientDataSet *DataSet)

{

  while (!DataSet->Eof)

  {

    TField *pSensitive = DataSet->FieldByName("SensitiveData");

    DataSet->Edit();

    pSensitive->AsString = DoEncrypt(pSensitive->AsString);

    DataSet->Post();

    DataSet->Next();

  }

}


UpdateStatus, OnUpdateData example

This example shows an OnUpdateData event handler that scans for deleted records and saves them to a log. LogDelete is a helper function which copies the data from the deleted record into the log.

/* this is the OnUpdateData event handler for the provider in the DBClientTest remote data module. */

void __fastcall TDBClientTest::ProviderUpdateData(TClientDataSet *DataSet)

{

  while (!DataSet->Eof)

  {

    if (DataSet->UpdateStatus == usDeleted)

      LogDelete(DataSet, UserName, Now());  // UserName is a global variable

    DataSet->Next();

  }

}


OnUpdateError example

When a user deletes a record that has already been deleted by another user, this error is reported back to the client.  The following example shows how to suppress this client-side error in an OnUpdateError event handler.

/* this is the OnUpdateError event handler for the provider in the DBClientTest remote data module. */

void __fastcall TDBClientTest::ProviderUpdateError(TClientDataSet *DataSet, EUpdateError *E, TUpdateKind UpdateKind, TResolverResponse &Response)

{

  if ((UpdateKind == ukDelete) && (E->ErrorCode == DBIERR_OPTRECLOCKFAILED))

    Response = rrIgnore;

  else

    Response = rrSkip;

}


Provider example

The following example shows how to use the Provider property to pass parameters to the remote dataset.  The remote dataset could contain more parameters than the two named in the variant array.  The call to the SetParams method of the Provider instructs the Provider component on the application server to set the CustNo parameter to 1231 and the Company parameter to 'Unisco';

Variant PData = VarArrayCreate(OPENARRAY(int,(0,1)),varVariant);

Variant Temp[2];

Temp[0] = Variant("CustNo");

Temp[1] = Variant(1231);

PData[0] = VarArrayOf(Temp,1);

Temp[0] = Variant("Company");

Temp[1] = Variant("Unisco");

PData[1] = VarArrayOf(Temp,1);

ClientDataSet1->Provider->SetParams(PData);

After the parameters are set, data is usually retrieved with a statement such as the following:

ClientDataSet1->AppendData(ClientDataSet->Provider->GetRecords(-1, RecCount), false);


CloneCursor, GotoCurrent, FindKey, CompareBookmarks, SetRange example

The following example uses a cloned cursor to determine whether the current record is within a specified range, and if so, applys the range to a client dataset.  The use of the cloned cursor allows the application to test a new range without changing the current range until it is determined that the new range is valid.

Note:	this example does not include any try .. catch statements to ensure that all allocations are freed if an exception occurs.  These should be added in any real application.

// create a second client dataset for checking the range

TClientDataSet *TempDataSet = new TClientDataSet(NULL);

/* clone the real dataset with Reset set to True

   so that the current range is not cloned  */

TempDataSet->CloneCursor(ClientDataSet1, true);

/* but we DO want the filters, if any,

   so apply them to the new client dataset */

if (ClientDataSet1->Filtered)

{

  TempDataSet->FilterOptions = ClientDataSet1->FilterOptions;

  TempDataSet->Filter = ClientDataSet1->Filter;

  TempDataSet->OnFilterRecord = ClientDataSet1->OnFilterRecord;

  TempDataSet->Filtered = true;

}

// now move to the same record, and get a bookmark for it

TBookmark RangeRec, CurRec;

TempDataSet->GotoCurrent(ClientDataSet1);

CurRec = TempDataSet->GetBookmark();

// try out new start of range

if (TempDataSet->FindKey(ARRAYOFCONST((Edit1.Text)))

{

  // starting value is valid, compare it to CurRec

  RangeRec = TempDataSet->GetBookmark();

  if (TempDataSet->CompareBookmarks(RangeRec, CurRec) <= 0)

  {

    // now try the end of the range

    if (TempDataSet->FindKey(ARRAYOFCONST((Edit2.Text)))

    {

      // ending value is valid, compare it to CurRec

      TempDataSet->FreeBookmark(RangeRec); // free old bookmark at range start

      RangeRec = TempDataSet->GetBookmark(); // replace it with bookmark at range end

      if (TempDataSet->CompareBookmarks(CurRec, RangeRec) <= 0)

        // the new range is good – apply it!

        TClientDataSet1->SetRange(ARRAYOFCONST((Edit1.Text)),ARRAYOFCONST((Edit2.Text)));

    }

  }

  TempDataSet->FreeBookmark(RangeRec);

}

TempDataSet->FreeBookmark(CurRec);

delete TempDataSet;


Splitter example

This example shows how to use a splitter to divide a form into resizeable panes.  All objects on the form are created dynamically in the OnCreate event handler of the form.  To run this example, add

#include <extctrls.hpp>

#include <filectrl.hpp>

to the unit file.

Note that when creating a splitter dynamically at runtime, it is important to set its position to the appropriate side of the control it will resize.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  // first add a directory list box to the form

  TDirectoryListBox *Dirs = new TDirectoryListBox(this);

  // align it on the left of the form

  Dirs->Parent = this;

  Dirs->Align = alLeft;

  // now add the splitter to divide the directory pane

  // from the file pane

  TSplitter *Split = new TSplitter(this);

  Split->Parent = this;

  // make sure the splitter is to the right

  // of the directory list box!

  Split->Left = Dirs->Left + Dirs->Width + 1;

  Split->Align = Dirs->Align; // give it the same alignment as the directory

  // each pane must be at least one quarter of the form’s width

  Split->MinSize = Form1->ClientWidth / 4;

  // Finally, create the last pane – a file list box

  TFileListBox *Files = new TFileListBox(this);

  Files->Parent = this;

  Files->Align = alClient;

  Dirs->FileList = Files; // link the file list box to the directory list box

}


TSplitter::OnMoved example

This example uses a splitter and two image controls to create a “slide show” effect.  The example displays an image (the current “slide”), which can be hidden behind a screen that looks like a venetian blind.  When the blind is pulled down to completely cover the current slide, the slide changes to a different image.  When the blind is raised, the new image appears.

To prepare this example, follow these steps:

1. Place an image control on the form.

Set the picture property to a bitmap of a venetian blind,

Set the Stretch property to True.

Set the Align property to alTop.

2. Add a splitter control to the form.

Set the Align property to alTop.

Set the Cursor property to crVSplit.

Set the OnMoved event handler to the code that appears below.

Set the MinSize property to 1.

3. Add a second image control to the form.

Set the Align property to alClient.

Set the Stretch property to True.

4. Select the form and add the OnCreate and OnDestroy event handlers that appear below.

5. Add the global variables below to the unit.

int CurImage;

Graphics::TBitmap *BMPs[5];

void __fastcall TForm1::Splitter1Moved(TObject *Sender)

{

  // check if the blind is closed

  if (Image2->Height <= 1)

  {

    // the blind is closed, change the current slide

    CurImage++;

    if (CurImage == 5)

       CurImage = 0;

    Image2->Picture->Bitmap = BMPs[CurImage];

  }

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  // Initialize the array of slides.

  // These must be freed in the OnDestroy event handler.

  BMPs[0] = new Graphics::TBitmap();

  BMPs[0]->LoadFromFile("C:\Windows\Fiddle Head.bmp");

  BMPs[1] = new Graphics::TBitmap();

  BMPs[1]->LoadFromFile("C:\Windows\Rhododendron.bmp");

  BMPs[2] = new Graphics::TBitmap();

  BMPs[2]->LoadFromFile("C:\Windows\Furry Dog.bmp");

  BMPs[3] = new Graphics::TBitmap();

  BMPs[3]->LoadFromFile("C:\Windows\Soap Bubbles.bmp");

  BMPs[4] = new Graphics::TBitmap();

  BMPs[4]->LoadFromFile("C:\Windows\Gone Fishing.bmp");

  CurImage = 0;

  Image2->Picture->Bitmap = BMPs[0];

}

void __fastcall TForm1::FormDestroy(TObject *Sender)

{

// clean up

  for (int I = 0; I < 5; I++)

    delete BMPs[I];

}


OnHTMLTag example

This example shows an OnHTMLTag event handler that replaces tags for images based on the information in a dataset and replaces table tags with an image of the entire dataset.  The image tags have the form <#IMAGE ImageID=5> while the table tags have the form <#TABLE>.  The table of images is represented by a table component named ImageTable, which is indexed by image ID.

void __fastcall TMyModule::ImageHTMLTag(TObject *Sender, TTag Tag, AnsiString TagString, TStrings TagParams, AnsiString &ReplaceText)

{

  int ImageID;

  switch (Tag)

  {

    case tgImage:

      ImageID = StrToInt(TagParams->Values["ImageID"]);

      if (ImageTable->FindKey(ARRAYOFCONST((ImageID))))

      {

        ReplaceText = AnsiString("<IMG SRC=") +

                       ImageTable->FieldByName("Filename")->AsString +

                       AnsiString(" ALT=") +

                       ImageTable->FieldByName("Description")->AsString +

                       AnsiString(">");

      }

      else

        ReplaceText = "(Unknown Image)"

      break;

    case tgTable:

      ReplaceText = DataSetTableProducer1->Content();

      break;

  }

}


Query, OnAction, Content example

This example shows a simple OnAction event handler that returns the content of a query table producer component as the response to matching HTTP request messages.

void __fastcall TInfoModule::WebModule1QueryAction(TObject *Sender, TWebRequest *Request, TWebResponse *Response, bool &Handled)

{

  if (Request->QueryFields->Count == QueryTableProducer1->Query->ParamCount)

    Response->Content = QueryTableProducer1->Content();

  if (Response->Content.IsEmpty())

    Handled = false; // indicate that the request was not handled

}


LockList, UnlockList example

The following example shows how to use the LockList and UnlockList methods to access a thread-safe version  of a TList object:

TList *pList = MyThreadList->LockList();

try

{

  for (int X = 0; X < pList->Count; X++)

    Something(pList->Items[X]);

}

catch (...)

{

  MyThreadList->UnlockList();

  throw;

}

MyThreadList->UnlockList();


TThread, Priority, Resume example

This example shows how to create a thread and start it running at a lower priority than the main execution thread. It assumes that the thread’s FreeOnTerminate property is True, so that there is no need to free the thread when it finishes.

TMyThread *SecondProcess = new TMyThread(true); // create but don’t run

SecondProcess->Priority = tpLower; // set the priority lower than normal

SecondProcess->Resume(); // now start the thread running


Synchronize example

This example shows how to call a button’s click method in a thread-safe manner:

void __fastcall TMyThread::PushTheButton(void)

{

  Button1->Click();

}

void __fastcall TMyThread::Execute()

{

  ...

  Synchronize((TThreadMethod)PushTheButton);

  ...

}


Execute, Socket, Write, Terminated, Active example

This example shows the execute method of a thread used to send requests to a server over a socket connection:

void __fastcall TMyClientThread::Execute()

{

  // create a TWinSocketStream for reading and writing

  TWinSocketStream *pStream = new TWinSocketStream(ClientSocket1->Socket, 60000);

  try

  {

    // fetch and process commands until the connection or thread is terminated

    while (!Terminated && ClientSocket1->Active)

    {

      try

      {

        char buffer[10];

        GetNextRequest(buffer); // GetNextRequest must be a thread-safe method

        // write the request to the server

        pStream->Write(buffer, strlen(buffer) + 1);

        // continue the communication (eg read a response from the server)

        ...

      }

      catch (Exception &E)

      {

        if (!E.ClassNameIs("EAbort"))

          Synchronize(HandleThreadException()); // you must write HandleThreadException

      }

    }

  }

  __finally

  {

    delete pStream;

  }

}


Copy, Component example

The following Copy method allows a TImage component to copy its picture to the Clipboard. This picture is ignored by the C++Builder IDE, but can be pasted into other applications.

void __fastcall TMyComponentEditor::Copy(void)

{

  WORD AFormat;

  int AData;

  HPALETTE APalette;

  ((TImage *)Component)->Picture->SaveToClipboardFormat(AFormat, AData, APalette);

  TClipboard *pClip = Clipboard(); // don’t clear the clipboard!

  pClip->SetAsHandle(AFormat, AData);

}


Template example

//---------------------------------------------------------------------------

#ifndef ExampleDialogH

#define ExampleDialogH

//---------------------------------------------------------------------------

#include <SysUtils.hpp>

#include <Controls.hpp>

#include <Classes.hpp>

#include <Forms.hpp>

#include <Dialogs.hpp>

//---------------------------------------------------------------------------

class PACKAGE TExampleDialog : public TCommonDialog

{

private:

protected:

public:

        __fastcall TExampleDialog(TComponent* Owner);

__published:

        __property Template;

};

//---------------------------------------------------------------------------

#endif

//---------------------------------------------------------------------------

#include <vcl.h>

#pragma hdrstop

#include "ExampleDialog.h"

#pragma package(smart_init)

//---------------------------------------------------------------------------

// ValidCtrCheck is used to assure that the components created do not have

// any pure virtual functions.

//

static inline void ValidCtrCheck(TExampleDialog *)

{

        new TExampleDialog(NULL);

}

//---------------------------------------------------------------------------

__fastcall TExampleDialog::TExampleDialog(TComponent* Owner)

        : TCommonDialog(Owner)

{

}

//---------------------------------------------------------------------------

namespace Exampledialog

{

        void __fastcall PACKAGE Register()

        {

                 TComponentClass classes[1] = {__classid(TExampleDialog)};

                 RegisterComponents("Samples", classes, 0);

        }

}

//---------------------------------------------------------------------------

bool TExampleDialog::MessageHook(TMessage Msg)

{

bool Value = MessageHook(Msg);

if (!Value)

{

// Check Msg for what you are trying

//to do in your Dialog component

if (Msg->Msg == SomeGlobalMsg)

{

// Do Something

ShowMessage("Recieved a SomeGloablMsg");

Value = true;

}

}

return Value;

}


Perform example

// Perform search on active DBRichedit

    	TDBRichEdit *DBRE = DtsDBRE;

    	if (MainPgCtl->ActivePage->Caption == "Code Examples")

        	DBRE = CodeTBRE;

        if (MainPgCtl->ActivePage->Caption == "TI's")

        	DBRE = TIDetDBRE;

    	if (MainPgCtl->ActivePage->Caption == "BC5 Bugs")

       	 	DBRE = BC5DBRE;

    	if (MainPgCtl->ActivePage->Caption == "Q and A's")

        	DBRE = DBQaRE;

        if (MainPgCtl->ActivePage->Caption == "TN's")

        	DBRE = TNRE;

    	PosFound = DBRE->Perform(EM_FINDTEXT, FT_WHOLEWORD, (LPARAM) (&MyTFindText));

    	FoundOne = PosFound != -1;

    	DBRE->Perform(EM_SETSEL, PosFound, PosFound + Search.Length());

    	DBRE->Perform(EM_SCROLLCARET, 0, 0);

    	DBRE->SetFocus();


CompareBookmarks example

bool CompareRecordsAtCursor()

{

// Make sure that neither bookmark is NULL

if (Table1->Bookmark && Table2->Bookmark)

return Table1->CompareBookmarks(Table1->Bookmark,

                                Table2->Bookmark))

}


OnKeyDown, Abort, Printing Example

The following code aborts a print job if the user presses Esc. Note that you should set KeyPreview to True to ensure that the OnKeyDown event handler of Form1 is called.

void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key, TShiftState Shift)

{

  if (Key == VK_ESCAPE && Printer()->Printing)

  {

    Printer()->Abort();

    MessageDlg("Printing aborted", mtInformation,

               TMsgDlgButtons() << mbOK,0);

  }

}


Aborted Example

The following code displays a dialog box if the print job was aborted:

if (Printer()->Aborted)

  Application->MessageBox("The print job did not finish printing.", "Alert!", MB_OK);


OnTimer, Interval, ActiveControl Example

The following event handler responds to timer events by moving the active control one pixel to the right:

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  Timer1->Interval = 100;

  if (ActiveControl)

    ActiveControl->Left = ActiveControl->Left + 1;

}


ActiveMDIChild, WindowState Example

This code uses a button on an MDI application. When the user clicks the button, the active MDI child form is minimized.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TForm* TheForm;

  TheForm = Form1->ActiveMDIChild;

  if (TheForm)

    TheForm->WindowState = wsMinimized;

}


AddChildObject Example

The following example adds a new child to the selected item’s list of child items in the tree view control. The new item is identified by the text ‘New Item’. The TBitmap object is attached to the new item.

TreeView1->Items->AddChildObject(TreeView1->Selected,

                                 "New Item",MyBitmap);


AddChildObjectFirst Example

The following example adds a new item to the selected item’s list of child items in the tree view control. The new item is added first in the list of child items. The new item is identified by the text ‘New Item’. The TBitmap object is attached to the new item.

TreeView1->Items->AddChildObjectFirst(TreeView1->Selected,

                                      "New Item",MyBitMap);


AddIndex Example

Table1->AddIndex("NumberName", "CustNo;CustName",

                 TIndexOptions() << ixUnique << ixCaseInsensitive);


AddObject, Count, Data Example

The following code defines a record type of TMyRec and a record pointer type of PMyRec.

typedef struct MyRec

{

  AnsiString FName, LName;

} TMyRec;

typedef TMyRec* PMyRec;

Assuming these types are used, the following code adds a node to TreeView1 as the last sibling of a specified node. A TMyRec record is associated with the added item. The FName and LName fields are obtained from edit boxes Edit1 and Edit2. The Index parameter is obtained from edit box Edit3. The item is added only if the Index is a valid value.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

PMyRec  MyRecPtr;

int TreeViewIndex;

TTreeNodes* pItems;

 MyRecPtr = new TMyRec;

 MyRecPtr->FName = Edit1->Text;

 MyRecPtr->LName = Edit2->Text;

 TreeViewIndex = StrToInt(Edit3->Text);

 pItems = TreeView1->Items;

 if (pItems->Count == 0)

   pItems->AddObject(NULL, "Item" + IntToStr(TreeViewIndex), MyRecPtr);

 else if ((TreeViewIndex < pItems->Count) && (TreeViewIndex >= 0))

      pItems->AddObject(pItems->Item[TreeViewIndex], "Item" + IntToStr(TreeViewIndex), MyRecPtr);

}

After an item containing a TMyRec record has been added, the following code retrieves the FName and LName values associated with the item and displays the values in a label.

void __fastcall TForm1::Button2Click(TObject *Sender)

{

Label1->Caption = PMyRec(TreeView1->Selected->Data)->FName + " " +

                 PMyRec(TreeView1->Selected->Data)->LName;

}


AddParam, RemoveParam Example

// Move all parameter info from Params2 to Params1

while (Params2->Count != 0)

{

// Grab the first parameter from Params2

  TempParam = Params2->Items[0];

  Params2->RemoveParam(TempParam); // Remove it from Params2

  Params1->AddParam(TempParam); // Add it to Params1

}


AfterCancel Example

This example updates the form’s status bar with a message when an AfterCancel event occurs.

void __fastcall TForm1::Table1AfterCancel(TDataSet *DataSet)

{

  TTable* TheTable = (TTable *)DataSet;

  StatusBar1->SimpleText = "Record changes cancelled for " +

                           TheTable->TableName;

}


AfterDelete, Format Example

This example displays a message on the form’s status bar indicating the table’s record count after a record is deleted.

Note that the ARRAYOFCONST macro requires an additional pair of parentheses even though there is only one argument.

void __fastcall TForm1::Table1AfterDelete(TDataSet *DataSet)

{

  StatusBar1->SimpleText =

    Format("There are now %d records in the table",

           ARRAYOFCONST(((int)DataSet->RecordCount));

}


AfterEdit Example

This example updates the form’s status bar with a message when an AfterEdit event occurs.

void __fastcall TForm1::Table1AfterEdit(TDataSet *DataSet)

{

  StatusBar1->SimpleText = "Editing record " +

                           IntToStr(DataSet->RecNo);

}


AfterInsert Example

This example updates the form’s status bar with a message when an AfterInsert event occurs.

void __fastcall TForm1::Table1AfterInsert(TDataSet *DataSet)

{

  StatusBar1->SimpleText = "Inserting new record";

}


AfterOpen Example

This example updates the form’s status bar with a message when an AfterOpen event occurs.

void __fastcall TForm1::Table1AfterOpen(TDataSet *DataSet)

{

  // now that the table is open, record information is available

  StatusBar1->SimpleText = "Record " + IntToStr(Table1->RecNo) + "of " + IntToStr(Table1->RecordCount);

}


AfterPost Example

This example updates the form’s status bar with a message when an AfterPost event occurs.

void __fastcall TForm1::Table1AfterPost(TDataSet *DataSet)

{

  StatusBar1.SimpleText = "Record changes complete";

}


AllowGrayed, State Example

This example uses a check box on a form. When the application runs, the check box is initially checked. When the user clicks it, the check box is unchecked. Clicking it again grays the check box.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  CheckBox1->AllowGrayed = true;

  CheckBox1->State = cbChecked;

}


Append, FieldValues, Post Example

This example appends a new record to a table when the user clicks a button. The two fields ALPHANUMERIC and INTEGER are filled from the contents of two edit controls.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Table1->Append();

  Table1->FieldValues["ALPHANUMERIC"] = Edit1->Text;

  Table1->FieldValues["INTEGER"] = StrToInt(Edit2->Text);

  Table1->Post();

}


AppendRecord Example

This statement appends a record to the Customer table. Note that Nulls are entered for some of the values, but are not required for missing values at the end of the array argument, i.e. after the Discount field.

Customer->AppendRecord(ARRAYOFCONST((CustNoEdit->Text,CoNameEdit->Text,AddrEdit->Text, Null, Null, Null, Null, Null, Null,DiscountEdit->Text)));


ApplyFilePath, FileEdit, FileList, DirLabel, DirList Example

This example uses a file list box, a directory list box, a filter combo box, a drive combo box, a label, an edit box, and a button on a form. When the user runs the application and enters a path or filename in the edit box and presses the button, all the controls update:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  FileListBox1->FileEdit = Edit1;

  FilterComboBox1->FileList = DirectoryListBox1->FileList = FileListBox1;

  DirectoryListBox1->DirLabel = Label1;

  DriveComboBox1->DirList = DirectoryListBox1;

  Button1->Default = true;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  FileListBox1->ApplyFilePath(Edit1->Text);

}


EditRangeStart, EditRangeEnd, ApplyRange Example

// Set start range based on text of Edit1 component

Customer->EditRangeStart();

Customer->FieldByName("Company")->AsString = Edit1->Text;

// Set end range based on value of Edit2 component

Customer->EditRangeEnd();

Customer->FieldByName("Company")->AsString := Edit2->Text;

Customer->ApplyRange(); // Apply the ranges


Arc Example

The following lines of code draw the top quarter of an arc bounded by the current window:

void __fastcall TForm1::FormPaint(TObject *Sender)

{

  TRect R = GetClientRect();  // Gets the rectangular

                              // coordinates of

                              // the current window.

  Canvas->Arc(R.Left, R.Top, R.Right, R.Bottom, R.Right, R.Top, R.Left, R.Top);

}


OnClick, ArrangeIcons Example

This code runs when the user chooses a menu item called Window | Arrange Icons:

void __fastcall TForm1::ArrangeIcons1Click(TObject *Sender)

{

  Form1->ArrangeIcons();

}


AsDateTime Example

The following statement converts a string to a date for insertion into a date field:

Table1->FieldByName("TimeStamp")->AsDateTime = StrToDateTime(Now());


TClipboard::Assign Example

The following line copies the bitmap of a speed button named SpeedButton1 to the Clipboard.  Note that you must add an include for Clipbrd.hpp to the unit file.

Clipboard()->Assign(SpeedButton1->Glyph);


TField::Assign Example

// Copy one date-time field to another

DateTimeField1->Assign(DateTimeField2);

// Copy a graphic field to a blob field

BlobField1->Assign(GraphicField1);

// Copy strings in a Memo component to a TMemoField

MemoField1->Assign(Memo1->Lines);


TParams::Assign, TParams::AssignValues Example

TParams *SavedParams;

...

// Initialize SavedParams

SavedParams = new TParams;

try

// Save the parameters for Query1

SavedParams->Assign(Query1->Params);

// Do something with Query1

...

// Restore the parameters to Query1

Query1->Params->AssignValues(SavedParams);

catch (...)

{

  // delete the saved parameters,

  // even if an exception occurs

  delete SavedParams

  throw;

}

delete SavedParams;


AutoEnable, EnabledButtons Example

The following code causes all of the buttons of MediaPlayer1 to become disabled when a bitmap button is clicked:

void __fastcall TForm1::BitBtn1Click(TObject *Sender)

{

  MediaPlayer1->AutoEnable = false;

  MediaPlayer1->EnabledButtons.Clear();

}


AutoRewind, Previous Example

The following code plays MediaPlayer. If AutoRewind is False, Previous is called to rewind after Play is finished.

MediaPlayer1->Wait = true;

MediaPlayer1->Play();

if (!MediaPlayer1->AutoRewind)

  MediaPlayer1->Previous();


TEdit::AutoSize Example

This example uses an edit box and a button on a form. When the user clicks the button, the font in the edit box enlarges, and the edit box enlarges also to accommodate the larger font size.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Edit1->AutoSize = true;

  Edit1->Font->Size = 20;

  Edit1->Text = "The edit box is taller now";

}


TLabel::AutoSize, TLabel::Caption Example

The following code keeps the size of the label control constant, even though the length of the label’s caption changes. As a result, the caption of the label is probably too long to display in the label when the user clicks the button:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Label1->AutoSize = false;

  Label1->Caption = "This string is too long as the caption of this label";

}


OpenDialog, FileName, Back, Next Example

The following example lets the user pick an .AVI video file using OpenDialog1 and opens that file in MediaPlayer1. Then, the Forward and Back buttons can be used to step through the .frames of the AVI clip in either direction.

void __fastcall TForm1::OpenClick(TObject *Sender)

{

  OpenDialog1->DefaultExt = "AVI";

  OpenDialog1->FileName = "*.avi";

  if (OpenDialog1->Execute())

  {

    MediaPlayer1->FileName = OpenDialog1->FileName;

    MediaPlayer1->Open();

  }

}

void __fastcall TForm1::BackClick(TObject *Sender)

{

  MediaPlayer1->Back();

}

void __fastcall TForm1::ForwardClick(TObject *Sender)

{

  MediaPlayer1->Next();

}


BeforeInsert, Insert, AsInteger, FieldByName Example

This example uses the BeforeInsert event to do data validation; if the StrToInt function raises an exception, the edit control’s contents are set to a valid value so the assignment to the INTEGER field in the table will succeed.

void __fastcall TForm1::Table1BeforeInsert(TDataSet *DataSet)

{

  try

  {

  // Make sure edit field can be converted to integer

  // this will throw an exception if it can’t

    StrToInt(Edit1->Text);

  }

  catch (...)

  {

    Edit1->Text = "0";

  }

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Table1->Insert();

  Table1->FieldByName("QUANTITY")->AsInteger = StrToInt(Edit1->Text);

  Table1->Post();

}


BeforePost, Abort Example

This example checks for a valid entry in a TDBEdit control and calls the Abort procedure if the control is empty; Abort cancels the post before it happens.

void __fastcall TForm1::Table1BeforePost(TDataSet *DataSet)

{

  if (DBEdit1->Text == "")

    Abort();

}


BeginUpdate, EndUpdate, Add, Count, Items Example

The following example adds a panel to the status bar control when the user clicks the button and adds a caption to the panel. The code uses BeginUpdate and EndUpdate to prevent repaints until the operation is complete.  A try...catch block ensures EndUpdate is called even when an exception occurs.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int PanelIndex;

  StatusBar1->Panels->BeginUpdate();

  PanelIndex = StatusBar1->Panels->Count - 1;

  try

  {

    StatusBar1->Panels->Add();

    PanelIndex++;

    StatusBar1->Panels->Items[PanelIndex]->Text = "Panel" + IntToStr(PanelIndex);

  }

  catch (...)

  {

    StatusBar1->Panels->EndUpdate();

    throw;

  }

  StatusBar1->Panels->EndUpdate();

}


BevelInner, BevelOuter, BorderWidth, BevelWidth Example

This example uses a panel component and a button named CreateStatusLine on a form. The code moves the panel to the bottom of the form when the user clicks the button and gives the panel the appearance of a status line by changing the value of the BevelInner, BevelOuter, BevelWidth, and BorderWidth properties.

void __fastcall TForm1::CreateStatusLineClick(TObject *Sender)

{

  Panel1->Align = alBottom;

  Panel1->BevelInner = bvLowered;

  Panel1->BevelOuter = bvRaised;

  Panel1->BorderWidth = 1;

  Panel1->BevelWidth = 1;

}


Canvas, Brush, Bitmap, FillRect Example

The following code loads a bitmap from a file and assigns it to the Brush of the Canvas of Form1:

Graphics::TBitmap *BrushBmp = new Graphics::TBitmap;

try

{

  BrushBmp->LoadFromFile("MyBitmap.bmp");

  Form1->Canvas->Brush->Bitmap = BrushBmp;

  Form1->Canvas->FillRect(Rect(0,0,100,100));

}

catch (...)

{

  Form1->Canvas->Brush->Bitmap = NULL;

  delete BrushBmp;

}

Form1->Canvas->Brush->Bitmap = NULL;

delete BrushBmp;


GetBookmark, GotoBookmark, FreeBookmark, FindPrior, Value, OnDataChange, BOF Example

This example uses a button to copy the value of a field in the previous record into the corresponding field in the current record.

void __fastcall TForm1::CopyDataClick(TObject *Sender)

{

  TBookmark *SavePlace;

  Variant PrevValue;

  // get a bookmark so that we can return to the same record

  SavePlace = Table1->GetBookmark();

  Table1->FindPrior();// move to prior record

  PrevValue = Table1->Fields[0]->Value; // get the value

  // Move back to the bookmark

  // this may not be the next record anymore

  // if something else is changing the dataset asynchronously

  Table1->GotoBookmark(SavePlace);

  Table1->Fields[0]->Value = PrevValue; // set the value

  Table1->FreeBookmark(SavePlace);

}

To ensure that the button is disabled when there is no previous record, the OnDataChange event of the DataSource detects when the user moves to the beginning of file (BOF property becomes True), and disables the button.

void __fastcall TForm1::Table1DataChange(TObject *Sender, TField *Field)

{

  CopyData->Enabled = !Table1->Bof;

}


BorderIcons Example

The following code removes a form’s Maximize button when the user clicks a button:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  BorderIcons = BorderIcons - (TBorderIcons()<< biMaximize);

}


 BoundsRect Example

This code resizes the active control to twice as wide and half as high:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TRect MyRect;

  MyRect = ActiveControl->BoundsRect;

  MyRect.Right = MyRect.Left + 2 * (MyRect.Right - MyRect.Left);

  MyRect.Bottom = MyRect.Top + (MyRect.Bottom - MyRect.Top) / 2;

  ActiveControl->BoundsRect = MyRect;

}


Visible, BringToFront Example

The following code uses two forms. Form1 has a button on it. The second form is used as a tool palette. This code makes the palette form visible, and ensures it is the top form by bringing it to the front.

To run this example, you must include Unit2.h in the Unit1 source file.

void __fastcall TForm1::ShowPaletteButtonClick(TObject *Sender)

{

  if (!Form2->Visible)

  {

    Form2->Visible = true;

    Form2->BringToFront();

  }

}


BrushCopy, CopyRect Example

The following code illustrates the differences between CopyRect and BrushCopy. The bitmap graphic ‘TARTAN.BMP’ is loaded into Bitmap and displayed on the Canvas of Form1. BrushCopy replaces the color black in the graphic with the brush of the canvas, while CopyRect leaves the colors intact.

Graphics::TBitmap *Bitmap;

TRect   MyRect, MyOther;

MyRect = Rect(10,10,100,100);

MyOther = Rect(10,111,100, 201);

Bitmap = new Graphics::TBitmap;

Bitmap->LoadFromFile("c:\windows\tartan.bmp");

Form1->Canvas->BrushCopy(MyRect, Bitmap, MyRect, clBlack);

Form1->Canvas->CopyRect(MyOther, Bitmap->Canvas, MyRect);

delete Bitmap;


BtnClick Example

This code allows a menu item called Record | Next to simulate clicking the Next button on a database navigator control, making the next record in the dataset the current record:

void __fastcall TForm1::RecordNextClick(TObject *Sender)

{

  DBNavigator1->BtnClick(nbNext);

}


MessageDlg, Cancel Example

The following fragment prompts the user to confirm changes to a record; if the user clicks Yes, the record is posted to the table, otherwise the changes are cancelled.

if (MessageDlg("Update Record?", mtConfirmation,

              TMsgDlgButtons() << mbYes << mbNo, 0) = mrYes)

  Table1->Post();

else

  Table1->Cancel();


Canvas, Ellipse, Color, Style Example

The following example paints a cross-hatched ellipse onto Image1 which is a TImage on the form when the user clicks on Button1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TCanvas *pCanvas = Image1->Canvas;

  pCanvas->Brush->Color = clRed;

  pCanvas->Brush->Style = bsDiagCross;

  pCanvas->Ellipse(0, 0, Image1->Width, Image1->Height);

}


OnDrawPanel, Canvas, Draw Example

The following code is the OnDrawPanel event handler of a status bar.  It draws each panel of the status bar, adding text and icons stored in ImageList1. The image list contains as many icons as there are header sections.

void __fastcall TForm1::StatusBar1DrawPanel(TStatusBar *StatusBar,

        TStatusPanel *Panel, const TRect &Rect)

{

  TCanvas *pCanvas = StatusBar->Canvas;

  pCanvas->Brush->Color = clRed;

  pCanvas->FillRect(Rect);

  pCanvas->Font->Color = clYellow;

  ImageList1->Draw(pCanvas,Rect.Left,Rect.Top, Panel->Index);

  pCanvas->TextOut(Rect.left + 30, Rect.top + 2, "Panel" + IntToStr(Panel->Index));

}


Capabilities Example

The following code determines whether the device opened by the media player control MediaPlayer1 uses a window to display output. If so, the output displays in a form named Form2:

if (MediaPlayer1->Capabilities.Contains(mpUsesWindow))

  MediaPlayer1->Display = Form2;


Cascade Example

This code runs when the user chooses a menu item called Window | Cascade:

void __fastcall TForm1::Cascade1Click(TObject *Sender)

{

  Cascade();

}


ColCount, RowCount, Cells Example

This code fills each cell with a number. The numbers are arranged in consecutive order by rows.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int I, J, K;

  K = 0;

  for (I = 0; I < StringGrid1->ColCount; I++)

    for (J = 0; J < StringGrid1->RowCount; J++)

      StringGrid1->Cells[I][J] = IntToStr(++K);

}


ClientRect Example

The following code uses ClientRect to find and draw a line from the top left to the bottom right of the current control.  It assumes that the current object has a Canvas property, such as can be found on descendants of TGraphicControl or TCustomControl.

MyControl->Canvas->MoveTo(MyControl->ClientRect.Left,

                          MyControl->ClientRect.Top);

MyControl->Canvas->LineTo(MyControl->ClientRect.Right,

                          MyControl->ClientRect.Bottom);


OnMouseDown, OnMouseMove, OnMouseUp, Panels, Text Example

The following example requires a form with a four-paneled status bar.  (Set the Width of the status panels to 150 before running this example).  When the user presses a mouse button, moves the mouse, and releases the mouse button, a rectangle is drawn on the form. When the mouse button is released, the rectangle appears on the form’s canvas. Its top-left and bottom-right corners are defined by the location of the mouse pointer when the user pressed and released the mouse button.  While the user drags the mouse, the location of the top, left, bottom, and right sides of the rectangle are displayed in the status bar.

int StartX, StartY; // Declare at the top of the form’s unit

// Use this code as the OnMouseDown event handler of the form:

void __fastcall TForm1::Button1MouseDown(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  StartX := X;

  StartY := Y;

}

// Use this code as the OnMouseUp event handler of the form:

void __fastcall TForm1::FormMouseUp(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  Form1->Canvas->Rectangle(StartX, StartY, X, Y);

  StatusBar1->Panels[0]->Text := "";

  StatusBar1->Panels[1]->Text := "";

  StatusBar1->Panels[2]->Text := "";

  StatusBar1->Panels[3]->Text := "";

}

// Use this code as the OnMouseMove event handler of the form:

void __fastcall TForm1::FormMouseMove(TObject *Sender, TShiftState Shift, int X, int Y)

{

  if (Shift.Contains(ssLeft)) // make sure button is down

  {

    if (Y > StartY)

    {

      StatusBar1->Panels[0]->Text = "Top: " + IntToStr(StartY);

      StatusBar1->Panels[2]->Text = "Bottom: " + IntToStr(Y);

    }

    else

    {

      StatusBar1->Panels[0]->Text = "Top: " + IntToStr(Y);

      StatusBar1.Panels[2].Text = "Bottom: " + IntToStr(StartY);

    }

    if (X > StartX)

    {

      StatusBar1->Panels[1]->Text = "Left: " + IntToStr(StartX);

      StatusBar1->Panels[3]->Text = "Right: " + IntToStr(X);

    }

    else

    {

      StatusBar1->Panels[1]->Text = "Left: " + IntToStr(X);

      StatusBar1->Panels[3]->Text := "Right: " + IntToStr(StartX);

    }

  }

}


Color Example

The following code changes the color of a shape control using the Color dialog box. The example displays the Color dialog box when the Button1 button is clicked, allowing the user to select a color with the dialog box. When a color value is selected with the dialog box, it is assigned to the shape control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (ColorDialog1->Execute)

    Shape1->Color = ColorDialog1->Color;

}


RemoveComponent, InsertComponent example

This example defines the MoveToModule function, which moves any nonvisual components on the form into a separate data module.  Note that the components are removed starting with the last component, so that the unprocessed portion of the Components array does not change

Note: This code does not save the form or data module to disk after the nonvisual components are moved.  If executed at runtime, the effect will not persist.

void MoveToModule(TForm *Source, TDataModule *Dest)

{

  int I;

  TComponent *Temp;

  for (I = Source->ComponentCount - 1; I >= 0; I--)

  {

    Temp = Source->Components[I];

    // only move components that are not controls

    if (dynamic_cast<TControl *>(Temp) == NULL)

    {

      Source->RemoveComponent(Temp);

      Dest->InsertComponent(Temp);

    }

  }

}


ConfigMode, AddStandardAlias, ExtractFilePath example

The following example specifically creates a local alias pointing to the application directory.  Note that this alias is automatically deleted when the application terminates and will not be saved to the BDE configuration file.

TConfigMode Save_Config = Session1->ConfigMode;

Session1->ConfigMode = cmSession;

try

{

  Session1->AddStandardAlias("TEMPDB", ExtractFilePath(ParamStr(0)), "PARADOX");

}

catch (...)

{

  Session1->ConfigMode = Save_Config;

  throw;

}

Session1->ConfigMode = Save_Config;


ControlCount, Controls, Top Example
CountrolCount, Controls, Top Example

This example uses an updown control and a group box on a form, with several controls contained within the group box.When the updown control is clicked, the controls within the group box are moved in the appropriate direction.

void __fastcall TForm1::UpDown1Click(TObject *Sender, TUDBtnType Button)

{

  int I;

  TControl *ChildControl;

  for (I = 0; I < GroupBox1->ControlCount; I++)

  {

    ChildControl = GroupBox1->Controls[I];

    if (Button == btNext)

      ChildControl->Top = ChildControl->Top + 15;

    else

      ChildControl->Top = ChildControl->Top - 15;

  }


CopyToClipboard, PasteFromClipboard Example

This example uses an edit box, a rich edit control, and a button on a form. When the user clicks the button, text is copied from the rich edit control and pasted into the edit box.  Note that only the text is pasted. If the rich edit control includes any formatting information, that is not pasted into the edit control.  If the destination were a rich edit control, the formatting information would be copied as well.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  RichEdit1->SelectAll();

  RichEdit1->CopyToClipboard();

  Edit1->Clear();

  Edit1->PasteFromClipboard();

  RichEdit1->SetFocus();

}


SelectAll, CutToClipboard Example

This example uses an edit box, a rich edit control, and a button on a form. When the user clicks the button, text is cut from the rich edit control and pasted into the edit box.  Note that only the text is pasted. If the rich edit control includes any formatting information, that is not pasted into the edit control.  If the destination where a rich edit control, the formatting information would be copied as well.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  // ensure that all the text is cut, not just the current selection

  RichEdit1->SelectAll();

  RichEdit1->CutToClipboard();

  Edit1->Clear();

  Edit1->PasteFromClipboard();

  RichEdit1->SetFocus();

}


 Count, Items, IsNull Example

// Assign -1 to any integer parameter which does not have a value

for (I = 0; I < Params->Count; I++)

{

  if (Params.Items[I]->IsNull &&

      Params.Items[I]->DataType == ftInteger)

    Params->Items[I]->AsInteger := -1;

}


CreateBlobStream, Edit, CopyFrom Example

The following example copies the data in the Notes field of Table1 to the Remarks field of Table2.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TBlobStream *Stream1, *Stream2;

  Stream1 =Table1->CreateBlobStream(Table1->FieldByName("Notes"), bmRead);

  try

  {

    Table2->Edit();

    Stream2 = Table2->CreateBlobStream(Table2->FieldByName("Remarks"), bmReadWrite);

    try

    {

      Stream2->CopyFrom(Stream1, Stream1->Size);

      Table2->Post();

    }

    catch (...)

    {

      delete Stream2;

      throw;

    }

    delete Stream2;

  }

  catch (...)

  {

    delete Stream1;

    throw;

  }

  delete Stream1;

}


 Table Creation Example

The following example demonstrates how to create a table.

Table1->Active = false; // The Table component must not be active

// First, describe the type of table and give it a name

Table1->DatabaseName = "BCDEMOS";

Table1->TableType := ttParadox;

Table1->TableName := "CustInfo";

// Next, describe the fields in the table

Table1->FieldDefs->Clear();

Table1->FieldDefs->Add("Field1", ftInteger, 0, True);

Table1->FieldDefs->Add("Field2", ftString, 30, False);

// Next, describe any indexes

Table1->IndexDefs->Clear();

/* In this case, the index has no name because it is a Paradox primary key */

Table1->IndexDefs->Add("","Field1", TIndexOptions() <<ixPrimary << ixUnique);

Table1->IndexDefs->Add("Fld2Index","Field2", TIndexOptions() << ixCaseInsensitive);

// Now that we have specified what we want, create the table

Table1->CreateTable();


CustomSort Example

The following code orders a list view in reverse alphabetical order on the click of a button. The callback function CustomSortProc calls the Windows API function lstrcmp and negates its return value.

int __stdcall CustomSortProc(int Item1, int Item2, int ParamSort)

{

  return -lstrcmp(((TListItem *)Item1)->Caption.c_str(),

                  ((TListItem *)Item2)->Caption.c_str());

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListView1->CustomSort(CustomSortProc, 0);

}


Database Example

// Do a transaction

Table1->Database->StartTransAction();

// Post some records with Table1

Table1->Database->Commit();


Active, DatabaseName Example

// The table should be closed when changing the database

Table1->Active = false;

try

{

  // First try to use an alias

  Table1->DatabaseName = "BCDEMOS";

  Table1->Active = true;

}

catch (EDatabaseError &e)

{

  // If that fails, try to use the drive and directory

  Table1->DatabaseName =

     "c:\Program Files\Borland\CBuilder\Examples\Data";

  Table1->Active = true;

}


DBHandle Example

This example uses the DBHandle property to make a call to the DbiGetDirectory BDE API function. Because it uses a BDE API function directly, you must add "#include <bde.hpp>" in the implementation section of the unit.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  char DefaultDir[250];

  char WorkDir[250];

  if(DbiGetDirectory(Table1->DBHandle, true, DefaultDir) != DBIERR_NONE)

    Application->MessageBox("Error getting default directory", "Error", MB_OK);

  else

    Application->MessageBox(DefaultDir, "Default Directory", MB_OK);

  if (DbiGetDirectory(Table1->DBHandle, false, WorkDir) != DBIERR_NONE)

    Application->MessageBox("Error getting current working directory", "Error", MB_OK);

  else

    Application->MessageBox(WorkDir, "Working Directory", MB_OK);

}


Items, Delete Example

The following example deletes an item in the tree view when the user clicks on it if a checkbox is checked.

void __fastcall TForm1::TreeView1MouseDown(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  THitTests HT;

if (CheckBox1->Checked and Sender->ClassNameIs("TTreeView"))

{

  TTreeView *pTV = (TTreeView *)Sender;

  HT = pTV->GetHitTestInfoAt(X,Y);

  if (HT.Contains(htOnItem))

    pTV->Items->Delete(pTV->GetNodeAt(X,Y));

}


DeleteTable Example

Table1->Active = false; // can’t delete table if it is active

// set properties to identify the table that should be deleted

Table1->DatabaseName = "BCDEMOS";

Table1->TableName = "Customer";

Table1->TableType = ttParadox;

// finally, delete the table

Table1->DeleteTable();


DisableControls, EnableControls, Eof Example

Usually DisableControls is called within the context of a try...catch block that reenables the controls even if an exception occurs. For example:

CustTable->DisableControls();

try

{

  CustTable->First();

  while (!CustTable->Eof)

  {

   // Process each record here

    .

    .

    .

    CustTable->Next();

  }

}

catch (...)

{

  CustTable->EnableControls();

  throw;

}

CustTable->EnableControls(); // re-enable if no exception


Drive, Directory Example

The following example assumes that a drive combo box, a file list box, and a directory list box are on a form. Add this code as the OnChange event handler for the drive combo box.  When the user changes the drive using the combo box,  the directory list box and file list box will update to reflect the new drive and the current directory on that drive.

void __fastcall TForm1::DriveComboBox1Change(TObject *Sender)

{

  DirectoryListBox1->Drive = FileListBox1->Drive = DriveComboBox1->Drive;

  FileListBox1->Directory = DirectoryListBox1->Directory;

}


EditKey, GotoKey Example

The following code uses the EditKey and GotoKey methods to move to a particular record on Table1.  The actual field values are not changed when making the assignments because of the call to EditKey.

Table1->EditKey();

Table1->FieldByName("State")->AsString = "CA";

Table1->FieldByName("City")->AsString = "Santa Barbara";

Table1->GotoKey();


Eject, Close, Enabled Example

This code ejects the CD from the CD-ROM player and shuts down the media player after 10 seconds. For the code to run correctly, you must have your CD audio device installed correctly, and the device must have software ejecting capabilities.

Word TimeOver;

void __fastcall TForm1::FormClick(TObject *Sender)

{

  MediaPlayer1->DeviceType = dtCDAudio;

  MediaPlayer1->Open();

  MediaPlayer1->Play();

  Timer1->Enabled = true;

  TimeOver = 0;

}

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  if (TimeOver == 10)

  {

    MediaPlayer1->Eject();

    MediaPlayer1->Close();

    // disable the timer, as we are done

    Timer1->Enabled = false;

  }

  else

    TimeOver++;

}


Empty Example

The following loads a file into Graphic1 if it does not already contain a graphic.

if (Graphic1->Empty)

  Graphic1->LoadFromFile("myfile.bmp");


EmptyTable Example

The following example uses a table component to empty a database table.  First the properties of the table component are set to specify the table that should be emptied.

Table1->Active = false;

Table1->DatabaseName = "BCDEMOS";

Table1->TableName = "CustInfo";

Table1->TableType = ttParadox;

Table1->EmptyTable();


EndPos, TrackLength Example

The following procedure begins playing the .WAV audio file from the beginning of the file to middle only.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  MediaPlayer1->FileName = "D:\WINAPPS\SOUNDS\CARTOON.WAV";

  MediaPlayer1->Open();

  MediaPlayer1->EndPos = MediaPlayer1->TrackLength[1]/2;

  MediaPlayer1->Play();

}


 Error, ErrorMessage Example

The following code opens MediaPlayer1. If an exception occurs, a message window displays the error number and string.

void __fastcall TForm1::BitBtn1Click(TObject *Sender)

{

  AnsiString MPError;

  try

  {

    MediaPlayer1->Open();

  }

  catch (...)

  {

    MPError = "Error " + IntToStr(MediaPlayer1->Error) + ": " + MediaPlayer1->ErrorMessage;

    Application->MessageBox(MPError.c_str(),NULL, MB_OK);

  }

}


 Exclusive, MessageBox Example

//Try to open Table1 with Exclusive true

// First, close Table1

Table1->Active = false;

do //until successful or user says to stop

{

  try

  {

    Table1->Exclusive = true; // See if it will open

    Table1->Active = true;

    	break; //if no error, exit the loop

  }

  catch(EDatabaseError &E)

  {

    //Ask if it is OK to retry

     if ( Application->MessageBox("Could not open Table exclusively - retry?", NULL, MB_OKCANCEL) != IDOK)

       throw; // throw to abort if user selects cancel

  }

} while (true);


Prepare, ExecProc Example

The following code executes the stored procedure:

StoredProc1->Params->Items[0]->AsString = Edit1->Text;

StoredProc1->Prepare();

StoredProc1->ExecProc();


SQL, ExecSQL Example

Query1->Close();

Query1->SQL->Clear();

Query1->SQL->Add("Delete from Country where Name = 'Argentina'");

Query1->ExecSQL();


TGridDataLink::FieldCount, TGridDataLink::Fields Example

If an application needs to access all the field components for each column of the TCustomDBGrid in order, Fields can be used with the FieldCount property.

for (I = 0,J = 0; I < GridDataLink1->FieldCount; I++)

{

  if (GridDataLink1->Fields[I])

  {

    // Fields[I] is the field component for the next column at runtime

    .

    .

    .

  }

}


TTable::FieldCount, TTable::Fields, TField::FieldName Example

This example displays a message box with the names of all fields in the table.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  AnsiString Info("The fields are: ");

  for(int i = 0; i < Table1->FieldCount; i++)

    Info = Info + Table1->Fields[i]->FieldName + ", ";

  ShowMessage(Info);

}


FilterIndex, Files, Strings, Append Example

This example uses an Open dialog box, a memo, and a button on a form. When the user clicks the button, the Open dialog box appears. When the user selects files in the dialog box and chooses the OK button, the first line from each of the files is added to the memo.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  FILE *stream;

  char FirstLine[512];

  OpenDialog1->Options.Clear();

  OpenDialog1->Options << ofAllowMultiSelect << ofFileMustExist;

  OpenDialog1->Filter = "Text files (*.txt)|*.txt|All files (*.*)|*.*";

  OpenDialog1->FilterIndex = 2; // start the dialog showing all files

  if (OpenDialog1->Execute())

  {

    for (int I = 0; I < OpenDialog1->Files->Count; I ++)

    {

      stream = fopen(OpenDialog1->Files->Strings[I].c_str(), "r");

      if (stream)

      {

        // read the first line from the file

        fgets(FirstLine, sizeof(FirstLine), stream);

        Memo1->Lines->Append(FirstLine);

        fclose(stream);

      }

    }

  }

}


TStringList::Find Example

This example uses a list box and a label on a form. When the application runs, a string list object is created and three strings are added to it. The Find method searches the strings to look for a match with the string ‘Flowers’. If the string is found, all the strings in the string list are added to the list box, and the index value of the ‘Flowers’ string appears in the caption of the label control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int Index;

  TStringList* MyList = new TStringList();

  MyList->Add("Animals");

  MyList->Add("Flowers");

  MyList->Add("Ocean");

  MyList->Sort(); // Find will only work on sorted lists

  if (MyList->Find("Flowers", Index))

  {

    ListBox1->Items->AddStrings(MyList);

    Label1->Caption = "Flowers has an index value of " + AnsiString(Index);

  }

  delete MyList;

}


FindField, AsString Example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  //Put the DataSource into Edit mode,

  // otherwise we won't be able to change the data

  DataSource1->Edit();

  // This is the safe way to change 'CustNo' field

  Table1->FindField("CustNo")->AsString = "1234";

  //This is *not* the safe way to change 'CustNo' field

  // Table1->Fields[0]->AsString = "1234";

}


SetFocus, SelStart, SelLength Example

The following OnFind event handler searches a memo component for the text specified in the FindText property of a find dialog component. If found, the first occurrence of the text in Memo1 is selected. The code uses the Pos function to compare strings, and stores the number of characters to skip when determining the selection position in the SkipChars variable. Because there is no handling of case, whole word, or search direction in this algorithm, it is assumed that the Options property of FindDialog1 was set to include frHideMatchCase, frHideWholeWord, and frHideUpDown.

void __fastcall TForm1::FindDialog1Find(TObject *Sender)

{

  for (int I = 0; I < Memo1->Lines->Count; I++)

  {

    int PosReturn = Memo1->Lines->Strings[I].Pos(FindDialog1->FindText);

    if (PosReturn) //found!

    {

      int Skipchars = 0;

      for (int J = 0; J < I; J++)

        Skipchars += Memo1->Lines->Strings[J].Length();

      Skipchars += I*2; // add CR/LF for all skipped lines

      Skipchars += PosReturn - 1;

      Memo1->SetFocus();

      Memo1->SelStart = Skipchars;

      Memo1->SelLength = FindDialog1->FindText.Length();

      break;

    }

  }

}


OnActiveControlChange, Focused Example

This example uses the OnActiveControlChange event to detect when focus changes on the form.  When focus changes, the active control is drawn in red.  All other windowed controls are given the window color from the control panel.

void _fastcall ColorControl(TObject *Sender)

{

  for (int I = 0; I < Form1->ControlCount; I++)

  {

    TWinControl *Temp = dynamic_cast<TWinControl *>(Form1->Controls[I]);

    if (Temp)

    {

      if (Temp->Focused())

        Temp->Color = clRed;

      else

        Temp->Color = clWindow;

    }

  }

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Screen->OnActiveControlChange = ColorControl;

}


OnDropDown, Sorted, Clear, BeginUpdate, EndUpdate Example

This example fills the list of a combo box with the set of available fonts when the user drops down the list.  The list is regenerated every time the list is dropped down, so if the application adds or removes fonts, the combo box stays current.

void __fastcall Form1::ComboBox1DropDown(TObject *Sender)

{

  FontCombo->Items->BeginUpdate(); // prevent repaints until done

  FontCombo->Items->Clear(); // empty the list of any old values

  FontCombo->Sorted = true; // make sure the font names are sorted

  FontCombo->Items = Screen->Fonts; // add the current list of fonts

  FontCombo->Items->EndUpdate(); //reenable painting

}


FormatCount, Formats Example

The following code adds each format on the Clipboard to ListBox1 when Button1 is clicked. note: You will need to include <Clipbrd.hpp>.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for(int i=0; i < Clipboard()->FormatCount;i++)

    ListBox1->Items->Add(IntToStr(Clipboard()->Formats[i]));

}


MenuItem, FormCount, Forms Example

This example assumes that the main form of the application has a main menu with a Window menu item.  The following code adds a separator, and the name of all forms to the Window menu.

TMenuItem *NewItem = new TMenuItem; // create the separator

NewItem->Caption = "-";

Window1->Add(NewItem); // add it to the Window menu

// now create and add a menu item for each form

for (int I = 0; i < Screen->FormCount; I++)

{

  NewItem = new TMenuItem;

  NewItem->Caption = Screen->Forms[I]->Name;

  Window1->Add(NewItem);

}


Rect, TextRect, FrameRect Example
Rect, TextRect FrameRect Example

The following code displays the text “Hello, world!” in a rectangle defined by the coordinates (10, 10) and (100, 100). After displaying the text with the TextRect method, the code draws a black, vertical line frame around the rectangle.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TRect TheRect;

  TheRect = Rect(10,10,100,100);

  Canvas->TextRect(TheRect, 10, 10, "Hello World");

  Canvas->Brush->Color = clBlack;

  Canvas->FrameRect(TheRect);

}


GetAliasNames, Count Example

TStringList *MyStringList = new TStringList();

try

{

  Session1->GetAliasNames(MyStringList);

  // fill a list box with alias names for the user to select from

  for (int I = 0; I < MyStringList->Count; I++)

    ListBox1->Items->Add(MyStringList->Strings[I]);

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


GetAliasParams Example

TStringList *MyStringList = new TStringList();

try

{

  Session1->GetAliasParams("BCDEMOS",MyStringList);

  // fill a list box with driver names for the user to select from

  ListBox1->Items = MyStringList;

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


Open, Close, GetAsHandle Example

The following code locks the memory for text on the Clipboard, then converts the text to an AnsiString.

AnsiString MyString;

int TextHandle;

char *pText;

Clipboard()->Open();

try

{

  TextHandle = Clipboard()->GetAsHandle(CF_TEXT);

  pText = (char *)GlobalLock((HGLOBAL)TextHandle);

  MyString = pText;

  GlobalUnlock((HGLOBAL)TextHandle);

}

catch (...)

{

  Clipboard()->Close();

  throw;

}

Clipboard()->Close();


 GetComponent, SetComponent Example

This example uses a button and a group box on a form. When the user clicks the button, the button is copied to the Clipboard and then retrieved from the Clipboard and placed in the new parent of the button, the group box. The name of the original button is changed to avoid having two components with the same name at the same time.

__fastcall TForm1::TForm1(TComponent* Owner): TForm(Owner)

{

  // Register the TButton class so that the clipboard can

  // read and write button objects

   TMetaClass *MetaClass = __classid(TButton);

   RegisterClasses(&MetaClass, 0);

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  // copy the button to the clipboard

  Clipboard()->SetComponent(Button1);

  // rename the button which is still on the form

  Button1->Name = "OriginalButton";

  // Now retrieve the button from the clipboard

  // and add it to GroupBox1

  // Note that the clipboard button is named Button1,

  // while the source button has been renamed

  // to "OriginalButton"

  Clipboard()->GetComponent(Self, GroupBox1);

}


IsBlob, DataSize, GetData, DisplayName Example

// Retrieve the "raw" data from Field1

if (!Field1->IsBlob()) // GetData does not work for BLOB fields

{

  void *MyBuffer = malloc(Field1->DataSize);

  try

  {

    if (!Field1->GetData(MyBuffer))

      MessageDlg(Field1->DisplayName + "is blank.",

                 mtInformation,

                 TMsgDlgButtons() << mbOK,0);

    else

      // Do something with the data;

  }

  catch (...)

  {

    free(MyBuffer);

    throw;

  }

  free(MyBuffer);

}


ParamByName, GetData, GetDataSize Example

// Allocate enough space to hold the CustNo data

void *Buffer = malloc(Query1->ParamByName("CustNo")->GetDataSize*())

// Retrieve the data

Query1->ParamByName("CustNo")->GetData(Buffer);

// do something with the data

...

free(Buffer);


GetDatabaseNames Example

TStringList *MyStringList = new TStringList();

try

{

  Session1->GetDatabaseNames(MyStringList);

  // fill a list box with database names for the user to select from

  ListBox1->Items = MyStringList;

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


GetDriverNames Example

TStringList *MyStringList = new TStringList;

try

{

  Session1->GetDriverNames(MyStringList);

  // fill a list box with driver names for the user to select from

  ListBox1->Items = MyStringList;

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


GetDriverParams Example

TStringList *MyStringList = new TStringList;

try

{

  Session1->GetDriverParams(MyStringList);

  // fill a list box with parameter names for the user to select from

  ListBox1->Items = MyStringList;

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


GetFirstNode, GetNext Example

The following example adds the Text for all items in the tree view to the list box.

TTreeNode *CurItem = TreeView1->Items->GetFirstNode();

while (CurItem)

{

  ListBox1->Items->Add(CurItem->Text);

  CurItem = CurItem->GetNext();

}


GetFormImage, Picture, Assign Example

This example uses an image, a button, and a shape component on a form. When the user clicks the button, an image of the form is stored in the FormImage variable and copied to the Clipboard. Then image of the form in then copied back to the image component, producing an interesting result, especially if the button is clicked multiple times.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Graphics::TBitmap *FormImage = GetFormImage();

  try

  {

    Clipboard()->Assign(FormImage);

    Image1->Picture->Assign(Clipboard());

  }

  catch(...)

  {

    delete FormImage;

    throw;

  }

  delete FormImage;

}

//------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Shape1->Shape = stEllipse;

  Shape1->Brush->Color = clLime;

  Image1->Stretch = true;

}


OpenCurrent, GetItemPath Example

This example uses a directory list box, a button, and a label on a form. When the user selects a directory in the directory list box and clicks the button, the selected directory opens, and the path of the second directory displayed in the list box appears as the caption of the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  DirectoryListBox1->OpenCurrent();

  Label1->Caption = DirectoryListBox1->GetItemPath(1);

}


GetResults, ParamByName Example

StoredProc1->Open();

while (!StoredProc1->Eof)

{

  StoredProc1->Next();

  // Do Something

}

StoredProc1->GetResults();

Edit1->Text = StoredProc1->ParamByName("Output");


GetSelTextBuf, SelText Example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int Size = Edit1->SelLength; //Get length of selected text in Edit1

  Size++;                      //Add room for null character

  char *Buffer = new char[Size];  //Creates Buffer dynamic variable

  Edit1->GetSelTextBuf(Buffer,Size); //Puts Edit1->Text into Buffer

  Edit2->Text = Buffer;

  delete Buffer;

}

Note: the same thing could be accomplished more simply as follows:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Edit2->Text = Edit1->SelText;

}


GetStoredProcNames Example

TStringList *MyStringList = new TStringList;

try

{

  Session1-> GetStoredProcNames("IB_EMPLOYEE", MyStringList);

 // fill a list box with stored procedure names

 // for the user to select from

  ListBox1->Items = MyStringList;

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


GetTableNames Example

TStringList *MyStringList = new TStringList;

try

{

  Session1-> GetTableNames("BCDEMOS","*.db",False,False, MyStringList);

 // fill a list box with the table names

   ListBox1->Items = MyStringList;

}

catch (...)

{

  delete MyStringList;

  throw;

}

delete MyStringList;


GetTextLen, GetTextBuf, Text Example

This example copies the text in an edit box into a null-terminated string, and puts this string in another edit box when the user clicks the button on the form.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int Size = Edit1->GetTextLen(); //Get length of string in Edit1

  Size++;                      //Add room for null character

  char *Buffer = new char[Size];  //Creates Buffer dynamic variable

  Edit1->GetTextBuf(Buffer,Size); //Puts Edit1->Text into Buffer

  Edit2->Text = Buffer;

  delete Buffer;

}

Note: the same thing could be accomplished more simply as follows:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Edit2->Text = Edit1->Text;

}


Glyph, NumGlyphs Example

These lines of code load a four-image bitmap into the Glyph property of a speed button, and specify the appropriate value for the NumGlyphs property:

SpeedButton1->Glyph->LoadFromFile("MYBITMAP.BMP");

SpeedButton1->NumGlyphs = 4;


SetKey, GotoNearest Example

Table1->SetKey();

Table1->FieldByName("State")->AsString = "CA";

Table1->FieldByName("City")->AsString = "Santa";

Table1->GotoNearest();


Graphic Example

The following code draws the graphic in Picture1 in the top-left corner of PaintBox1.

PaintBox1->Canvas->Draw(0,0 Picture1->Graphic);


TForm::Handle Example

The following code uses the Windows API function ShowWindow to display Form2 as an icon, but does not activate it.

ShowWindow(Form2->Handle, SW_SHOWMINNOACTIVE);


OnIdle, HandleMessage Example

The following code demonstrates background processing using the OnIdle event, and using the HandleMessage method to permit messages or background processing to get through.

Note:	You must add MyIdleHandler to the public Form1 methods in the header file for the unit.

// global variables to show the order of events

int  XPos, YPos, Delta;

// This is a utility procedure to display messages

// add this at the beginning of the unit

void StatusMsg(TForm *Form, TCanvas *Canvas, char *Message, bool Bkg)

{

  if (!Bkg)

    Canvas->Font->Style << fsBold; // foreground messages are bold

  Canvas->TextOut(XPos, YPos, Message);

  if (!Bkg)

    Canvas->Font->Style.Clear();

  // change Xpos and YPos to prepare for the next message

  YPos += Delta;

  if (YPos >= Form->ClientHeight)

  {

    YPos = 10;

    XPos += 100;

  }

  if (XPos >= Form->ClientWidth - 100)

  {

    if (Canvas->Font->Color == clRed)

      Canvas->Font->Color = clBlack;

    else

      Canvas->Font->Color = clRed;

    XPos = 10;

  }

}

/* This is the OnIdle event handler. It is set in the Form’s OnCreate event handler, so you need only add it as a private method of the form.  Usually it would perform some background processing for the application.  This one simply writes a message to let you know when it’s there. */

void __fastcall TForm1::MyIdleHandler(TObject *Sender, bool &Done)

{

  StatusMsg(Form1, Canvas, "This represents a background process.", true);

}

/* This is the OnCreate event handler for Form1.  It initializes global values and sets the application’s OnIdle event handler */

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Button1->Caption = "Do not yield";

  Button2->Caption  = "Handle Message";

  Application->OnIdle = MyIdleHandler;

  XPos = 10;

  YPos = 10;

  if (Canvas->Font->Height > 0)

    Delta = Canvas->Font->Height + 1;

  else

    Delta = 1 - Canvas->Font->Height;

}

/* This is the OnClick event handler for Button1.  It simulates a lengthy process */

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int X, Y;

  StatusMsg(Form1, Canvas, "The Button1Click handler is starting", false);

  for (int I = 0; I < 100; I++)

  {

    randomize();

    for (int J = 0; J < 100; J++)

      Y = random(J);

    X = random(I);

  }

  StatusMsg(Form1, Canvas, "The Button1Click handler is done", false);

}

/* this is the OnClick event handler for button2.  It simulates a lengthy process that allows other messages to be processed. */

void __fastcall TForm1::Button2Click(TObject *Sender)

{

  int X, Y;

  StatusMsg(Form1, Canvas, "The Button2Click handler is starting", false);

  for (int I = 0; I < 100; I++)

  {

    randomize();

    for (int J = 0; J < 100; J++)

    {

      Y = random(J);

      // Yield to OnIdle or other messages

      Application->HandleMessage();

    }

    X = random(I);

  }

  StatusMsg(Form1, Canvas, "The Button2Click handler is done", false);

}


HasFormat, AsText Example

This example uses a button and an edit control on a form. When the user clicks the button, any text on the clipboard is pasted into the edit control.  If there is no text on the clipboard, a message box appears.

Note:	to use this example, you must include <Clipbrd.hpp>.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (Clipboard()->HasFormat(CF_TEXT))

    Edit1->Text = Clipboard()->AsText;

  else

    Application->MessageBox("The clipboard does not contain text.", NULL, MB_OK);

}


HelpCommand Example

This example uses a bitmap button on a form. When the user clicks the button, the Help contents screen of the specified Help file appears.

void __fastcall TForm1::BitBtn1Click(TObject* Sender)

{

  Application->HelpFile = "MyHelp.hlp";

  Application->HelpCommand(HELP_CONTENTS, 0);

}


HelpContext Example

This example uses a bitmap button on a form. When the user clicks the button, the screen with the context number of 714 in the DATA.HLP Help file appears.  Note that using constants for HelpContext numbers makes the code easier to read:

const DATANOTFOUND (714)

void __fastcall TForm1::BitBtn1Click(TObject *Sender)

{

  Application->HelpFile = "DATA.HLP";

  Application->HelpContext(DATANOTFOUND);

}


HelpFile, HelpJump Example

This example uses a bitmap button on a form. When the user clicks the button, the Help screen describing the HelpJump property in the BCBVCL3.HLP file appears, because the HelpJump property screen has the a JumpID string of ‘TApplication_HelpJump'.

Void __fastcall TForm1::BitBtn1Click(TObject *Sender)

{

  Application->HelpFile := "BCBVCL3.HLP";

  Application->HelpJump("TApplication_HelpJump");

}


Hide Example

This code uses a button and a timer on a form. When the user clicks the button, the form disappears for the period of time specified in the Interval property of the timer control, then the form reappears:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Timer1->Enabled = true;

  Hide();

}

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  Visible = true;

  Timer1->Enabled = false;

}


Hint, ShowHint Example

This example uses an edit box and a list box on a form. Items are added to the list box and a Help Hint is assigned to both controls. The last statement enables the Help Hints for the entire application.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Edit1->Hint = "Enter your name";

  Edit1->ShowHint = true;

  char string[10];

  char index[3];

  for(int i = 1; i <= 10; i++)

  {

    strcpy(string, "Item");

    itoa(i, index, 10);

    strcat(string, index);

    ListBox1->Items->Add(string);

  }

  ListBox1->Hint = "Select an item";

  ListBox1->ShowHint = true;

  Application->ShowHint = true;

}

Note: To see an example that displays the hints of controls in some place other than in a Help Hint box, see the OnHint example.


Hints Example

This example uses a database navigator and a button on a form. When the user clicks the button, the Help Hints for the navigator are modified.

Void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TStringList *NewStrings = new TStringList;

  NewStrings->Add("Beginning of dataset");

  NewStrings->Add("Previous Record");

  NewStrings->Add(""); // don’t change hint for the 3rd button

  NewStrings->Add("End of dataset");

  DBNavigator1->Hints = NewStrings;

  DBNavigator1->ShowHint = true;

}


ClientWidth, HorzScrollBar, Position, Range, Increment, Visible Example

This example starts the form in a position scrolled so that the right hand edge shows:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  /* set the width of the form window to display 300 pixels in the client area */

  ClientWidth = 300;

  /* now set the range to twice the client width.

   This means that the form has a logical size that is twice as big as the physical window.  Note that Range must always be at least as big as ClientWidth! */

  HorzScrollBar->Range = 600;

  /* start the form fully scrolled */

  HorzScrollBar->Position = HorzScrollBar->Range - ClientWidth;

  /* clicking the scroll arrows moves the form 10 pixels */

  HorzScrollBar->Increment = 10;

  HorzScrollBar->Visible := true;  // Show the scrollbar

}


TForm.Icon Example

This code assigns an icon to a form when the form is created:

__fastcall TForm1::TForm1(TComponent* Owner): TForm(Owner)

{

  Icon->LoadFromFile("C:\\PROGRAM FILES\\BORLAND\\CBUILDER\\IMAGES\\ICONS\\EARTH.ICO");

}


OpenPictureDialog, TApplication::Icon Example

The following code allows the user to use a dialog box to redefine the icon for the application at run time. When the user clicks Button1, OpenDialog1 executes and the user specifies an icon filename. The Icon is then assigned to the application.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  OpenPictureDialog1->DefaultExt = GraphicExtension(TIcon);

  OpenPictureDialog1->FileName = GraphicFileMask(TIcon);

  OpenPictureDialog1->Filter = GraphicFilter(TIcon);

  OpenPictureDialog1->Options.Clear();

  OpenPictureDialog1->Options << ofFileMustExist << ofHideReadOnly << ofNoChangeDir;

  while (true)

  {

    if (OpenPictureDialog1->Execute())

    {

      if (!OpenPictureDialog1->Options.Contains(ofExtensionDifferent))

      {

        Application->Icon->LoadFromFile(OpenPictureDialog1->FileName);

        break;

      }

      else // reset Options to remove ofExtensionDifferent

      {

        OpenPictureDialog1->Options.Clear();

        OpenPictureDialog1->Options << ofFileMustExist << ofHideReadOnly << ofNoChangeDir;

      }

    }

    else // user cancelled

      break;

  }

}


IndexDefs, Update, Count, Items, IndexName, Fields, Name Example

This example uses the IndexName property to sort the records in a table on the CustNo and OrderNo fields.

Table1->Active = false;

Table1->Exclusive = true;

// Get the current available indicies

Table1->IndexDefs->Update();

/* Find one which combines Customer Number ("CustNo") and Order Number ("OrderNo") }

for (int I = 0; I < Table1->IndexDefs->Count; I++)

  if (Table1->IndexDefs->Items[I]->Fields == String("CustNo;OrderNo"))

  {

    // set that index as the current index for the table

    Table1->IndexName = Table1->IndexDefs->Items[I]->Name;

  }

Table1->Exclusive = false;

Table1->Active = true;


IndexFields, IndexFieldCount Example

The following code calculates the total length of the index and assigns it to the variable TotalLen;

int TotalLen = 0;

for (int i = 0; i < Table1->IndexFieldCount; i++)

  TotalLen += Table1->IndexFields[i]->DataSize;


TList::IndexOf Example

The following code adds an object to MyList if it isn’t already in the list.

if (MyList->IndexOf(TheObject)== -1)

  MyList->Add(TheObject);


OnChange, IndexOf Example

This example uses a file list box, a directory list box, and a label on a form. When the user uses the directory list box to change directories, a message appears and the color of the form changes if the file AUTOEXEC.BAT is in the new directory. The code is written in the OnChange event of the directory list box:

void __fastcall TForm1::DirectoryListBox1Change(TObject *Sender)

{

  FileListBox1->Directory = DirectoryListBox1->Directory;

  if (FileListBox1->Items->IndexOf("AUTOEXEC.BAT") > -1)

  {

    Color = clYellow;

    Label1->Caption = "You are in the root directory!";

  }

}


IndexOfName, Count, Names, Value Example
IndexOfName, Count, Names, Values Example

The following example updates the strings in a list box given the strings contained in another list box. If a string in the source list box has the form Name=Value and the destination list box contains a string with the same Name part, the Value part in the destination list box will be replaced by the source’s value.

void MergeStrings(TStrings *Dest, TStrings *Source)

{

  for (int i = 0; i < Source->Count; i++)

  {

    if (Source->Strings[i].Pos("=") > 1)

    {

      int DI = Dest->IndexOfName(Source->Names[i]);

      if (DI > -1)

        Dest->Values[DI] = Source.Values[i];

    }

  }

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  MergeStrings(ListBox1->Items,ListBox2->Items);

}


Insert, Selected, Index Example

The following example inserts a list item after the selected item in the list view.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TListItem *InsertItem =

    ListView1->Items->Insert(ListView1->Selected->Index);

  InsertItem->Caption = Edit1->Text;

}


InsertControl, RemoveControl Example

This example uses a button and two group boxes.  When the user clicks the button, the other group box becomes the parent of the button, so the button moves inside the other group box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (Button1->Parent == GroupBox1)

  {

    GroupBox1->RemoveControl(Button1);

    GroupBox2->InsertControl(Button1);

  }

  else

  {

    GroupBox2->RemoveControl(Button1);

    GroupBox1->InsertControl(Button1);

  }

}

Note that it was necessary to remove the button from the Controls property of the form before the button actually moves into the group box.

This code accomplishes the same thing:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (Button1->Parent == GroupBox1)

    Button1->Parent = GroupBox2;

  else

    Button1->Parent = GroupBox1;

}


InsertObject, Name, ItemAtPos, ClassType, ClassParent Example

For the following example, add a status bar, a list box, and any other components to Form1.  Set the SimplePanel property of the status bar to True, using the object inspector.The following code fills a list box with the names of all components on the form when the form is created.  References to the components themselves are inserted along with the names.  The components are all inserted at the front of the list, so that the last component added to the form is the first component in the list.

When the user right-clicks the name of an object in the list, the component’s coordinates are displayed on the status bar.  Note that because we are using the right-click, the item need not be selected.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < ComponentCount; i++)

    ListBox1->Items->InsertObject(0,

                                  Components[i]->Name,

                                  (TObject *)Components[i]);

}

void __fastcall TForm1::ListBox1MouseUp(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  if (Button == mbRight)

  {

    TClass ClassRef;

    int Index = ListBox1->ItemAtPos(Point(X,Y), true);

    // only components that are controls have a position

    // make sure the component is a control

    for (ClassRef = ListBox1->Items->Objects[Index]->ClassType();

         ClassRef != NULL;

         ClassRef = ClassRef->ClassParent())

      if (String(ClassRef->ClassName()) == "TControl")

      {

        TControl *TheObject = (TControl *)ListBox1->Items->Objects[Index];

        StatusBar1->SimpleText =

          TheObject->Name + " is at (" +

          IntToStr(TheObject->Left) + ", " +

          IntToStr(TheObject->Top) + ")";

         break;

      }

    if (ClassRef == NULL) // if it wasn't a control

      MessageBeep(0);

  }

}


InsertRecord Example

This statement appends a record to the Customer table. Note that Nulls are entered for some of the values, but are not required for missing values at the end of the array argument.

Customer->InsertRecord(ARRAYOFCONST((CustNoEdit->Text,CoNameEdit->Text,AddrEdit->Text, Null, Null, Null, Null, Null, Null,DiscountEdit->Text)));


IsMasked Example

This example tests the masked edit box to determine if it has an edit mask. If it doesn’t an edit mask is assigned. The edit mask is one for dates in the MM/DD/YY format:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if(!MaskEdit1->IsMasked)

    MaskEdit1->EditMask = "!99/99/00;1;_";

}


ItemRect Example

This example uses a list box on a form. When the user clicks one of the items in the list box, a beep occurs if the mouse is in the first half of the item. A similar technique can be used to detect “hot” regions in an owner-draw list box:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  ListBox1->Items->Add("Hello");

  ListBox1->Items->Add("New");

  ListBox1->Items->Add("World");

}

void __fastcall TForm1::ListBox1MouseUp(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  TRect ItemBounds;

  if (Button == mbLeft)

  {

    ItemBounds = ListBox1->ItemRect(ListBox1->ItemIndex);

    if (Y > ItemBounds.Top &&

        Y < ItemBounds.Bottom &&

        X > ItemBounds.Left &&

        X < (ItemBounds.Left + ItemBounds.Right)/2)

      MessageBeep(0);

  }

}


Add, AddChild Example

The following example demonstrates how to add nodes and child nodes to a TTreeView control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TTreeNode *Node1;

  TreeView1->Items->Clear(); // remove any existing nodes

  // Add a root node

  TreeView1->Items->Add(NULL, "RootNode1");

  /* Set MyTreeNode to first node intree view and add a child node to it */

  Node1 = TreeView1->Items->Item[0];

  TreeView1->Items->AddChild(Node1,"ChildNode1");

  // Add another root node

  TreeView1->Items->Add(Node1, "RootNode2");

  /* Reset Node1 to RootNode2 and add a child node to it */

  Node1 = TreeView1->Items->Item[2];

  TreeView1->Items->AddChild(Node1,"ChildNode2");

  /* Reset Node1 to ChildNode2 and add a child node to it */

  Node1 = TreeView1->Items->Item[3];

  TreeView1->Items->AddChild(Node1,"ChildNode2a");

   /* Add another child to ChildNode2 following ChildNode2a */

  TreeView1->Items->AddChild(Node1,"ChildNode2b");

  // add another root node

  TreeView1->Items->Add(TreeView1->Items->Item[0], "RootTreeNode3");

}


Count, Items, Enabled Example

The following code disables all the subitems of MenuItem1.

for (int i = 0; i < MenuItem1->Count; i++)

{

  MenuItem1->Items[i]->Enabled = false;

}


Add, Count, Items Example

This example creates a list object and inserts two records into it. The value of the record fields are written on a paintbox:

typedef struct AList

{

  int I;

  char C;

} TAList;

typedef TAList* PAList;

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  PAList AStruct;

  TList *MyList = new TList;

  // fill the TList

  AStruct = new TAList;

  AStruct->I = 100;

  AStruct->C = 'Z';

  MyList->Add(AStruct);

  AStruct = new TAList;

  AStruct->I = 100;

  AStruct->C = 'X';

  MyList->Add(AStruct);

  // Go through the list, writing the elements to the

  // canvas of a paintbox component.

  int Y = 10; // position on canvas

  for (int i = 0; i < MyList->Count; i++)

  {

    AStruct = (PAList) MyList->Items[i];

    PaintBox1->Canvas->TextOut(10, Y, IntToStr(AStruct->I));

    Y += 30;  // Increment Y Value again

    PaintBox1->Canvas->TextOut(10, Y, AStruct->C);

    Y += 30;  //Increment Y Value

  }

  // Clean up – must free memory for the items as well as the list

  for (int i = 0; i < MyList->Count; i++)

  {

    AStruct = (PAList) MyList->Items[i];

    delete AStruct;

  }

  delete MyList;

}


KeyExclusive Example

/* Limit the range from 1351 to 1356,

  including 1351 but excluding 1356 */

Table1->EditRangeStart(); // set the beginning key

Table1->IndexFields[0]->AsString = "1351";

// Include 1351 in the range.

// Note that KeyExclusive applys to the range start

// because of the call to EditRangeStart

Table1->KeyExclusive = false;

Table1->EditRangeEnd(); // set the ending key

Table1->IndexFields[0]->AsString = "1356";

// Exclude 1356 from the range

// Note that KeyExclusive now applys to the range end

// because of the call to EditRangeEnd

Table1->KeyExclusive = true;

// Tell the table to establish the range

Table1->ApplyRange();


KeyPreview, OnKeyDown, OnKeyUp Example

This example changes a form’s color to aqua when the user presses a key, even when a control on the form has the focus. When the user releases the key, the form returns to its original color.

TColor FormColor;

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  KeyPreview = true;

}

void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key, TShiftState Shift)

{

  FormColor = Form1->Color;

  Form1->Color = clAqua;

}

void __fastcall TForm1::FormKeyUp(TObject *Sender, WORD &Key, TShiftState Shift)

{

  Form1->Color = FormColor;

}


BitBtn::Kind Example

This example uses three bitmap buttons on a form. When the application runs, the Kind property for each bitmap button is set, and the BitBtn1 button (the OK button) becomes the default button.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  BitBtn1->Kind = bkOK;

  BitBtn2->Kind = bkCancel;

  BitBtn3->Kind = bkHelp;

}


Items, ItemIndex, Kind Example

This example uses a radio group box and a scroll bar on a form. When the user selects one of the radio buttons, the scroll bar changes orientation accordingly.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  RadioGroup1->Items->Add("Vertical");

  RadioGroup1->Items->Add("Horizontal");

  RadioGroup1->ItemIndex = 2;

}

void __fastcall TForm1::RadioGroup1Click(TObject *Sender)

{

  if (RadioGroup1->Items->Strings[RadioGroup1->ItemIndex] == "Vertical")

    ScrollBar1->Kind = sbVertical;

  else if (RadioGroup1->Items->Strings[RadioGroup1->ItemIndex] == "Horizontal")

    ScrollBar1->Kind = sbHorizontal;

}


TList::Last Example

This example inserts two records into a list object and displays the contents of the last record in the list on the form:

typedef struct AList

{

  int I;

  char C;

} TAList;

typedef TAList* PAList;

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  PAList AStruct;

  TList *MyList = new TList;

  // fill the TList

  AStruct = new TAList;

  AStruct->I = 100;

  AStruct->C = 'Z';

  MyList->Add(AStruct);

  AStruct = new TAList;

  AStruct->I = 99;

  AStruct->C = 'X';

  MyList->Add(AStruct);

// display the contents of the last record

  AStruct = (PAList) MyList->Last();

  Edit1->Text = IntToStr(AStruct->I);

  Edit2->Text = AStruct->C;

  // Clean up – must free memory for the items as well as the list

  for (int i = 0; i < MyList->Count; i++)

  {

    AStruct = (PAList) MyList->Items[i];

    delete AStruct;

  }

  delete MyList;

}


OnChange, Lines Example

The following code assigns the value to the Lines property of DDEClientItem1 to the Lines of Memo1. This code is executed in the OnChange event handler of DDEClientItem1, so whenever the client is updated, the new data from the server is displayed.

void __fastcall TForm1::DdeClientItem1Change(TObject *Sender)

{

  Memo1->Lines = DDEClientItem1->Lines;

}


MoveTo, LineTo Example

The following code draws a line from the upper left corner of a form to the mouse position when the mouse is moved, creating a “rubber band” effect.

void __fastcall TForm1::FormMouseMove(TObject *Sender, TShiftState Shift, int X, int Y)

{

  /* first call FillRect to paint the surface of the form.

  this removes any previously drawn lines (and anything else!) */

  Canvas->FillRect(ClientRect);

  Canvas->MoveTo(0, 0);

  Canvas->LineTo(X, Y);

}


AutoDisplay, LoadMemo Example

This example uses a database memo that is connected to a BLOB text field in the dataset. The current value of the BLOB field does not appear until the user clicks the memo.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  DBMemo1->AutoDisplay = false;

}

void __fastcall TForm1::DBMemo1Click(TObject *Sender)

{

  DBMemo1->LoadMemo();

}


Mappings Example

TStringList *Maps = new TStringList;

Maps->Clear();

// Map the CustomerNum field to CustNo

Maps->Add("CustNo=CustomerNum");

// Leave the SSN field mapped to SSN

Maps->Add("SSN");

BatchMove1->Mappings = Maps;

delete Maps;


Margin, Range Example

This example uses a button and a label on a form. Place the label near the left side of the form, and place the button somewhere near the middle of the form. When the user runs the application, a horizontal scroll bar does not appear, because no control on the form is close enough to the right edge. Each time the user clicks the button, the button moves 25 pixels to the right, and the calculated Range value is reported in the caption of the label. Repeatedly clicking the button eventually moves the button close enough to the edge of the form (within the Margin amount) so that a horizontal scroll bar appears.  Note that the Range property is continuously updated as the button moves to the right.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  HorzScrollBar->Margin = 25;

  HorzScrollBar->Increment = 10;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Button1->Left = Button1->Left + 25;

  Label1->Caption = IntToStr(HorzScrollBar->Range);

}


 Filter, Mask Example

This example uses a filter combo box and a file list box on a form. When the user selects a filter in the filter combo box, the file list box displays only files which match the selected mask:

void __fastcall TForm1::FilterComboBox1Change(TObject *Sender)

{

  FileListBox1->Mask = FilterComboBox1->Mask;

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  FilterComboBox1->Filter = "All files (*.*)|*.*| Header files (*.h;*.hpp)|*.h;*.hpp";

}


 MasterSource, MasterFields Example

Suppose you have a master table named Customer that contains a CustNo field, and you also have a detail table named Orders that also has a CustNo field. To display only those records in Orders that have the same CustNo value as the current record in Customer, write this code:

Orders->MasterSource = "CustSource";

Orders->MasterFields = "CustNo";

If you want to display only the records in the detail table that match more than one field value in the master table, specify each field and separate them with a semicolon.

Orders->MasterFields = "CustNo;SaleDate";


Options, MaxFontSize, MinFontSize Example

This example uses a Font dialog box, a button, and a label on a form. When the user clicks the button, the Font dialog box appears. The font sizes available are within the range of 8 to 14. When the user chooses OK, the selected font is applied to the caption of the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  FontDialog1->Options.Clear();

  FontDialog1->Options << fdLimitSize;

  FontDialog1->MaxFontSize = 14;

  FontDialog1->MinFontSize = 8;

  if (FontDialog1->Execute())

    Label1->Font = FontDialog1->Font;

}


Printing Example

This example uses a button, a Page Control, and a Print dialog box on a form. When the user clicks the button, the print dialog is displayed.  The user can select any subset of the pages in the page control for printing.  The selected pages are then printed.

To run this example successfully, you must include <Printers.hpp> in your unit file.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  PrintDialog1->Options.Clear;

  PrintDialog1->Options << poPageNums << poSelection;

  PrintDialog1->FromPage = PrintDialog1->MinPage = 1;

  PrintDialog1->ToPage = PrintDialog1->MaxPage =

                         PageControl1->PageCount;

  if (PrintDialog1->Execute())

  {

    int Start, Stop;

    // determine the range the user wants to print

    switch (PrintDialog1->PrintRange)

    {

      case prSelection:

        Start = PageControl1->ActivePage->PageIndex;

        Stop = Start;

        break;

      case prPageNums:

        Start = PrintDialog1->FromPage - 1;

        Stop =  PrintDialog1->ToPage - 1;

        break;

      default:  // prAllPages

        Start = PrintDialog1->MinPage - 1;

        Stop = PrintDialog1->MaxPage - 1;

        break;

    }

    // now, print the pages

    Printer()->BeginDoc();

    for (int i = Start; i <= Stop; i++)

    {

      PageControl1->Pages[i]->PaintTo(Printer()->Handle, 10, 10);

      if (i != Stop)

        Printer()->NewPage();

    }

    Printer()->EndDoc();

  }

}


MDIChildCount, MDIChildren, Close Example

The following code closes all the MDI children of Form1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for(int i = 0; i < MDIChildCount; i++)

    MDIChildren[i]->Close();

}


ModalResult, ShowModal Example

The following methods in a form are used as a modal dialog box. The methods cause the dialog box to terminate when the user clicks either the OK or Cancel button, returning mrOK or mrCancel from ShowModal, respectively. You could also set the ModalResult value to mrOk for the OK button and mrCancel for the Cancel button to accomplish the same thing. When the user clicks either button, the dialog box closes.

void __fastcall TOKRightDlg::OKBtnClick(TObject *Sender)

{

  ModalResult = mrOk;

}

void __fastcall TOKRightDlg::CancelBtnClick(TObject *Sender)

{

  ModalResult = mrCancel;

}

This code brings up the modal dialog from Form1 when a button is clicked.  It causes a Beep if the OK button is clicked.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (OKRightDlg->ShowModal() == mrOK)

    MessageBeep(0);

}


OnNotify, Mode Example
OnNotify, Mode, Notify Example

The following code declares an array of strings named ModeStr.  The Caption of a form displays the string describing the current mode of the device.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  MediaPlayer1->Notify = true;

}

AnsiString ModeStr[] = {"Not ready", "Stopped", "Playing", "Recording", "Seeking", "Paused", "Open"};

void __fastcall TForm1::MediaPlayer1Notify(TObject *Sender)

{

  Form1->Caption = ModeStr[(int) MediaPlayer1->Mode];

  /* Note we must reset the Notify property to True so that we are notified the next time the mode changes */

  MediaPlayer1->Notify = true;

}


MouseToCell Example

This example uses a string grid on a form. When the user selects a cell in the grid and releases the mouse button, the column and row coordinates for the cell appear in the cell. The code for displaying the coordinates is written in the OnMouseUp event handler:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  StringGrid1->DefaultColWidth = 100;

}

void __fastcall TForm1::StringGrid1MouseUp(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  long Column, Row;

  StringGrid1->MouseToCell(X, Y, Column, Row);

  StringGrid1->Cells[Column][Row] = "Col " + AnsiString((int)Column) +

                                    ",Row " + AnsiString((int) Row);

}


ItemIndex, Move Example

This example uses a list box and a button on a form. The list box contains items when the form appears. When the user clicks the button, the selected item in the list box is moved to the top of the list box:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  ListBox1->MultiSelect = false;

  Button1->Caption = "Move to Top";

  for (int i = 1; i <= 10; i++)

    ListBox1->Items->Add("Item " + IntToStr(i));

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Move(ListBox1->ItemIndex, 0);

}


Mode, Execute, MovedCount, KeyViolCount Example

The following code uses the BatchMove component to add records to a table.  After the records have been added, the number of new records is reported on the status line.

BatchMove1->Mode = batAppend;

BatchMove1->AbortOnKeyViol = false;

BatchMove1->Execute();

StatusBar1->SimpleText = IntToStr(BatchMove1->MovedCount - BatchMove1->KeyViolCount) + " records added.";


Printer, Canvas, PageWidth, PageHeight Example

This example uses a button on a form. When the user clicks the button, a bitmap is printed, centered on the page. To run this example successfully, include <Printers.hpp> in your unit file.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TPrinter Prntr = Printer();

  Graphics::TBitmap *bmp = new Graphics::TBitmap();

  bmp->LoadFromFile("MyPicture.bmp");

  Prntr->BeginDoc();

  Prntr->Canvas->Draw((Prntr->PageWidth - bmp->Width)/2,

                      (Prntr->PageHeight - bmp->Height)/2,

                      bmp);

  Prntr->EndDoc();

  delete bmp;

}


NormalizeTopMosts, RestoreTopMosts Example

The following code causes “stay on top” forms to allow a MessageBox to appear on top. After the message box is closed, the topmost forms are restored so that they continue to float to the top.

Application->NormalizeTopMosts();

Application->MessageBox("This should be on top.", "Message Box", MB_OK);

Application->RestoreTopMosts();


NotifyValue Example

This example uses a media player component named MediaPlayer1. When the application runs, the code attempts to play a CD in the CD audio device, If it is not successful, the application displays an error dialog.

Before you can run this example, you must have a CD audio device installed correctly.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  MediaPlayer1->Visible = false;

  MediaPlayer1->Notify = true;

  MediaPlayer1->DeviceType = dtCDAudio;

  MediaPlayer1->Open();

  MediaPlayer1->Play();

  if (MediaPlayer1->NotifyValue != nvSuccessful)

    Application->MessageBox("Error playing CD audio.", NULL, MB_OK);

}


OnActivate, ComponentCount, Components, ClassNameIs Example

The following code Sets the Datasource for a DBGrid component in Form2 to the currently selected data source in a list provided in Form1.  This allows users to specify the desired information in form1, and then move to Form2 to view the information.

void __fastcall TForm2::FormActivate(TObject *Sender)

{

  DBGrid1->DataSource = (TDataSource *)

    Form1->ListBox1->Objects[Form1->ListBox1->ItemIndex];

}

Here is the code on Form1 that fills the list box:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < DataModule2->ComponentCount; i++)

  {

    if (DataModule2->Components[i]->ClassNameIs("TDataSource"))

      ListBox1->Items->AddObject(DataModule2->Components[i]->Name,

        (TObject *)DataModule2->Components[i]);

  }

}


OnActiveFormChange, ActiveForm Example

This example uses a two forms with a button on the first form. When the user clicks the button, the second form appears. As the user switches between forms, the form that is active is colored aqua.

Note:	you must include the unit header for form 2 to the unit file for form 1, add add the public ColorForm method to the header for form 1’s unit.

void __fastcall TForm1::ColorForm(TObject *Sender)

{

  Color = clBtnFace;

  Form2->Color = clBtnFace;

  Screen->ActiveForm->Color = clAqua;

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Screen->OnActiveFormChange = ColorForm;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Form2->Show();

}


Font, Execute, OnApply, Assign Example

This example takes an edit control, a button, and a rich edit control on a form.  When the user presses the button, a Font dialog appears.  When the user clicks the Apply button in the Font dialog, the currently selected font is applied to the active control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TFontDialog1->Options << fdApplyButton;

  TFontDialog1->Execute();

}

void __fastcall TForm1::FontDialog1Apply(TObject *Sender, HWND Wnd)

{

  if (ActiveControl->ClassNameIs("TEdit"))

   ((TEdit *)ActiveControl)->Font->Assign(TFontDialog1->Font);

  else if (ActiveControl->ClassNameIs("TRichEdit"))

    ((TRichEdit *)ActiveControl)->SelAttributes->Assign(TFontDialog1->Font);

  else

    MessageBeep(0);

}


TMediaPlayer::OnClick Example

This example uses a label and a media player on a form. When the user clicks one of the media player buttons, the caption of the label indicates which button was clicked. For this example to run successfully, you must have a CD audio device installed correctly.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  MediaPlayer1->DeviceType = dtCDAudio;

  MediaPlayer1->Open();

  MediaPlayer1->Left = 20;

  MediaPlayer1->Top = 12;

  Label1->Top = 44;

  Label1->Left = 20;

  Label1->Color = clYellow;

  Label1->Font->Name = "Arial";

  Label1->Caption = "Click Me";

}

void __fastcall TForm1::MediaPlayer1Click(TObject *Sender, TMPBtnType Button, bool &DoDefault)

{

  switch (Button)

  {

    case btPlay:

      Label1->Caption = "Playing";

      Label1->Left = 20;

      break;

    case btPause:

      Label1->Caption = "Paused";

      Label1->Left = 48;

      break;

    case btStop:

      Label1->Caption = "Stopped";

      Label1->Left = 76;

      break;

    case btNext:

      Label1->Caption = "Next";

      Label1->Left = 104;

      break;

    case btPrev:

      Label1->Caption = "Previous";

      Label1->Left = 132;

      break;

    case btStep:

      Label1->Caption = "Step";

      Label1->Left = 160;

      break;

    case btBack:

      Label1->Caption = "Back";

      Label1->Left = 188;

      break;

    case btRecord:

      Label1->Caption = "Record";

      Label1->Left = 216;

      break;

    case btEject:

      Label1->Caption = "Eject";

      Label1->Left = 244;

      break;

  }

}


TDBNavigator::OnClick Example

The following code determines which database navigator button was clicked and displays a message identifying the name of the button.

void __fastcall TForm1::DBNavigator1Click(TObject *Sender, TNavigateBtn Button)

{

  AnsiString BtnName;

  switch (Button)

  {

    case nbFirst:  BtnName = "First Record"; break;

    case nbPrior:  BtnName = "Prior Record"; break;

    case nbNext:   BtnName = "Next Record"; break;

    case nbLast:   BtnName = "Last Record"; break;

    case nbInsert: BtnName = "Insert Record"; break;

    case nbDelete: BtnName = "Delete Record"; break;

    case nbEdit:   BtnName = "Edit"; break;

    case nbCancel: BtnName = "Cancel Edits"; break;

    case nbRefresh: BtnName = "Refresh Data"; break;

  }

  Application->MessageBox(BtnName + " button clicked.", "Navigator", MB_OK);

}


OnOpen, OnClose, ExecuteMacro Example

The following code enables the send macro button and macro edit control when the DDE conversation begins, and disables them when it ends.

void __fastcall TForm1::DdeClientConv1Open(TObject *Sender)

{

  SendMacroButton->Enabled = true;

  EditMacro->Enabled = true;

}

void __fastcall TForm1::DdeClientConv1Close(TObject *Sender)

{

  SendMacroButton->Enabled = false;

  EditMacro->Enabled = false;

}

void __fastcall TForm1::SendMacroButtonClick(TObject *Sender)

{

  DdeClientConv1->ExecuteMacro(EditMacro->Text.c_str(), true);

}


OnColEnter, OnColExit, SelectedField, DisplayLabel Example

The following code concatenates an asterisk to the display label of a field when the column is entered, and removes it when another column is selected. Note that FirstTime is a Boolean field that prevents characters from being deleted the first time a column is exited before it is entered.

static bool FirstTime = true;

void __fastcall TForm1::DBGrid1ColEnter(TObject *Sender)

{

  DBGrid1->SelectedField->DisplayLabel = "* " + DBGrid1->SelectedField->DisplayLabel;

  FirstTime = false;

}

void __fastcall TForm1::DBGrid1ColExit(TObject *Sender)

{

  if (!FirstTime)

  {

    char *TheLabel = DBGrid1->SelectedField->DisplayLabel.c_str();

    TheLabel += 2;

    DBGrid1->SelectedField->DisplayLabel = TheLabel;

  }

}


OnDeactivate, Minimize Example

The following code minimizes an application when it’s deactivated. Note that AppDeactivate should be declared a method of TForm1.

void __fastcall TForm1::AppDeactivate(TObject *Sender)

{

  Application->Minimize();

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->OnDeactivate = AppDeactivate;

}


OnDestroy Example

The following code allocates a TBitmap object that is used by the application when the main form is first created.  The OnDestroy method frees the bitmap as the application shuts down.

Graphics::TBitmap *LogoBmp;

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  LogoBmp = new Graphics::TBitmap();

  LogoBmp->LoadFromFile("Logo.Bmp");

}

void __fastcall TForm1::FormDestroy(TObject *Sender)

{

  delete LogoBmp;

}


OnDragOver, OnDragDrop Example

This code comes from an application that contains a list box and three labels, each with a different font and color.  The DragMode property for each of the labels is dmAutomatic.  The user can select a label and drag it to a list box and drop it. When the label is dropped, the items in the list box assume the color and font of the dropped label.

This OnDragOver event handler permits the list box to accept a dropped label:

void __fastcall TForm1::ListBox1DragOver(TObject *Sender, TObject *Source, int X, int Y, TDragState State, bool &Accept)

{

   Accept = Source->ClassNameIs("TLabel");

}

This OnDragDrop event handler implements the drop behavior.

void __fastcall TForm1::ListBox1DragDrop(TObject *Sender, TObject *Source, int X, int Y)

{

  if (Sender->ClassNameIs("TListBox") && Source->ClassNameIs("TLabel"))

  {

    TListBox *DestList = (TListBox *)Sender;

    DestList->Font = ((TLabel *)Source)->Font;

    DestList->Color = ((TLabel *)Source)->Color;

  }

}


OnDrawCell, Canvas, DrawFocusRect Example

The following code uses the bitmaps in an imagelist component to draw the contents of each cell in a draw grid.  It draws a focus rectangle around the cell that has focus.

void __fastcall TForm1::DrawGrid1DrawCell(TObject *Sender, long Col, long Row, TRect &Rect, TGridDrawState State)

{

  long index = Row * DrawGrid1->ColCount + Col;

  DrawGrid1->Canvas->Brush->Color = clBackGround;

  DrawGrid1->Canvas->FillRect(Rect);

  ImageList1->Draw(DrawGrid1->Canvas,Rect.Left,Rect.Top,index);

  if (State.Contains(gdFocused))

    DrawGrid1->Canvas->DrawFocusRect(Rect);

}


OnEndDrag Example

This code displays a message on the status bar indicating whether a label was successfully dropped into and accepted by a another control.

void __fastcall TForm1::StatusEndDrag(TObject *Sender, TObject *Target, int X, int Y)

{

  AnsiString S = ((TLabel *)Sender)->Name + " was dropped and ";

  if (Target)

    S = S + "accepted!";

  else

    S = S + "rejected.";

  StatusBar1->Panels->Items[0]->Text = S;

}


OnEnter, OnExit Example

This example uses an edit box and a memo control on a form. When either the edit box or the memo is the active control, it is colored yellow. When the active control becomes inactive, the color of the control returns to the Windows system color for a window.

void __fastcall TForm1::Edit1Enter(TObject *Sender)

{

  Edit1->Color = clYellow;

}

void __fastcall TForm1::Edit1Exit(TObject *Sender)

{

  Edit1->Color = clWindow;

}

void __fastcall TForm1::Memo1Enter(TObject *Sender)

{

  Memo1->Color = clYellow;

}

void __fastcall TForm1::Memo1Exit(TObject *Sender)

{

  Memo1->Color = clWindow;

}


OnException, ShowException, Terminate Example

In addition to displaying the exception message, which happens by default, the following code shuts down the application when a VCL exception is not caught and handled.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->OnException = AppException;

}

void __fastcall TForm1::AppException(TObject *Sender, SysUtils::Exception *E)

{

  Application->ShowException(E);

  Application->Terminate();

}


OnExecuteMacro Example

The following code clears the contents of a memo in the server application if the appropriate message is sent from the client application.

void __fastcall TForm1::DdeServerConv1ExecuteMacro(TObject *Sender, TStrings *Msg)

{

  if (Msg->Strings[0] == "Edit|Clear")

    Memo1->Clear();

}


OnFilterRecord Example

The following example shows how to use a field comparison when filtering records on a local table, by using the OnFilterRecord event.

void __fastcall TForm1::Table1FilterRecord(TDataSet *DataSet, bool &Accept)

{

  Accept = (DataSet->FieldValues["DateOfPayment"] >

            DataSet->FieldValues["DateOfPurchase"] + 30);

}


OnGetEditMask Example

This example specifies an edit mask in a string grid to limit the cells that contain telephone numbers, as indicated by a label cell in the first row:

void __fastcall TForm1::StringGrid1GetEditMask(TObject *Sender, long ACol, long ARow, AnsiString &Value)

{

  if (StringGrid1->Cells[ACol, 0] == "Phone Number")

    Value = "!\(999\)000-0000;1";

}


OnGetEditText Example

The following code lowercases the text for a string grid cell when the user begins to edit it.

void __fastcall TForm1::DrawGrid1GetEditText(TObject *Sender, long ACol, long ARow, AnsiString &Value)

{

  Value = AnsiLowerCase(Value);

}


OnHelp Example

The following code changes the Help file depending on the active form, before WinHelp is called. AppHelp is assigned to the OnHelp event handler of Application in the OnCreate event of Form1.

bool __fastcall TForm1::AppHelp(Word Command, long Data, bool &CallHelp)

{

  Application->HelpFile = Screen->ActiveForm->Name + ".hlp";

  CallHelp = true;

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->OnHelp = AppHelp;

}


OnHide Example

This example uses two forms, each with a label and a button. When the user clicks a button, the other form appears and the current form disappears. Also, a message appears in the label of the form that is showing, indicating that the other form is hidden.

This is the implementation of Unit1:

#include <vcl\vcl.h>

#pragma hdrstop

#include "Unit1.h"

#include "Unit2.h"  // We must include unit2’s header file too!

//-------------------------------------------------------------

#pragma link "Grids"

#pragma resource "*.dfm"

TForm1 *Form1;

//----------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner): TForm(Owner)

{

}

//------------------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Form2->Show();

  Hide();

}

//------------------------------------------------------------------

void __fastcall TForm1::FormHide(TObject *Sender)

{

  Form2->Label1->Caption = "Form1 is hiding";

}

This is the implementation section of Unit2:

#include <vcl\vcl.h>

#pragma hdrstop

#include "Unit2.h"

#include "Unit1.h"  // We must include unit1’s header file too!

//-------------------------------------------------------------

#pragma link "Grids"

#pragma resource "*.dfm"

TForm2 *Form2;

//-------------------------------------------------------------

#pragma resource "*.dfm"

TForm2 *Form2;

//------------------------------------------------------------------

__fastcall TForm2::TForm2(TComponent* Owner): TForm(Owner)

{

}

//------------------------------------------------------------------

void __fastcall TForm2::Button1Click(TObject *Sender)

{

  Form1->Show();

  Hide();

}

//------------------------------------------------------------------

void __fastcall TForm2::FormHide(TObject *Sender)

{

  Form1->Label1->Caption = "Form2 is hiding";

}


OnKeyPress Example

This event handler displays a message dialog box specifying which key was pressed:

void __fastcall TForm1::FormKeyPress(TObject *Sender, char &Key)

{

  char keyString[25];

  KeyString[0] = Key;

  strcpy(&keyString[1], " Was Pressed");

  Application->MessageBox(keyString , "Key Press", MB_OK);

}


OnMessage Example

The following code handles a custom message that the application sends to itself when a file is ready for reading.

const WM_FILEREADY = WM_USER + 2000;

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->OnMessage = AppMessage;

}

void __fastcall TForm1::AppMessage(tagMSG &Msg, bool &Handled)

{

  if (Msg.message == WM_FILEREADY)

  {

    Memo1->Lines->LoadFromFile(AnsiString((char *)Msg.lParam));

    Handled = true;

  }

  /* for all other messages, Handled remains False so that other message handlers can respond */

}


 OnPokeData, Lines, Text Example

The following code uses two DDE server items to protect poked data from being lost by a DDE server application. DoOnPoke is the OnPokeData event handler for the DDE server item named DDETestItem. When data is poked, The Text for the DDE server item named FInPoke is set to 'True', telling the client application not to send any more data.  After the poked data is stored in the Lines property of Memo2,  the Text property of FInPoke is set back to 'False', telling the client application that more data can safely be sent.

void __fastcall TDdeSrvrForm::doOnPoke(TObject *Sender)

{

  FInPoke->Text = "True";

  Memo2->Lines = DdeTestItem->Lines;

  FInPoke->Text = "False";

}


OnPopup Example

The following code enables the Paste item from the pop-up menu if the Clipboard has text data.

void __fastcall TForm1::PopupMenu1Popup(TObject *Sender)

{

  Paste1->Enabled = Clipboard->HasFormat(CF_TEXT);

}


TReplaceDialog::Options Example

The following code calls the user-defined routine DoReplace if the Replace button was clicked, or calls the user-defined routine DoReplaceAll if the Replace All button was clicked.

void __fastcall TForm1::ReplaceDialog1Replace(TObject *Sender)

{

  TReplaceDialog *dlg = (TReplaceDialog *)Sender;

  if (dlg->Options.Contains(frReplace))

    DoReplace(dlg->FindText, dlg->ReplaceText);

  else if (dlg->Options.Contains(frReplaceAll))

    DoReplaceAll(dlg->FindText, dlg->ReplaceText);

}


OnReplace, ReplaceText Example

The following event handler searches a TMemo object called Memo1 and replaces FindText with ReplaceText. It uses TMemo’s SelStart, SelLength, and SelText properties.

void __fastcall TForm1::ReplaceDialog1Replace(TObject *Sender)

{

  TReplaceDialog *dlg = (TReplaceDialog *)Sender;

  /* perform a global case-sensitive search for FindText in Memo1 */

  int SelPos = Memo1->Lines->Text.Pos(dlg->FindText);

  if (SelPos > 0)

  {

    Memo1->SelStart = SelPos - 1;

    Memo1->SelLength = dlg->FindText.Length();

    // Replace selected text with ReplaceText

    Memo1->SelText = dlg->ReplaceText;

  }

  else

    MessageBeep(0);

}


OnResize Example

The following code keeps the right edge on Button1 against the right edge of Form1 when Form1 is resized.

void __fastcall TForm1::FormResize(TObject *Sender)

{

  Button1->Left = Form1->ClientWidth - Button1->Width;

}


OnResizeRequest Example

The following code resizes the rich edit control to accomodate growing or shrinking lines of text:

void __fastcall TForm1::RichEditResizeRequest(TObject *Sender, TRect Rect)

{

  ((TRichEdit *)Sender)->BoundsRect = Rect;

}


OnRowMoved Example

The following code displays the number of rows a row was moved in the first cell of the row.

void __fastcall TForm1::StringGrid1RowMoved(TObject *Sender, long FromIndex, long ToIndex)

{

  int delta = (FromIndex > ToIndex) ? (FromIndex-ToIndex) : (ToIndex-FromIndex);

  StringGrid1->Cells[0][ToIndex] = IntToStr(delta);

}


Min, Max, Position, SmallChange, LargeChange, OnScroll Example

This example shows how to use a scrollbar to navigate the pages of a page control.  To run this example, place a scrollbar and a page control on a form.  Right click the page control and add 12 pages to it.  Add the following code to the OnCreate event of the form, the OnChange event of the page control, and the OnScroll event of the scrollbar.

Note that the LargeChange and SmallChange properties are set to automatically change the active page by one tab or one row respectively.  The OnScroll event is used to make the actual change in the page control, while the OnChange event of the page control ensures that the scrollbar is kept in sync with changes made directly to the page control.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  // First, initialize the page control

  PageControl1->TabWidth = PageControl1->ClientWidth/4 - 1;

  PageControl1->ActivePage = PageControl1->Pages[0];

  /* set up the scrollbar to reflect

     the structure of the page control */

  ScrollBar1->Max = PageControl1->PageCount - 1;

  ScrollBar1->Min = 0;

  ScrollBar1->SmallChange = 1;

  // set LargeChange to a single row of tabs

  ScrollBar1->LargeChange = PageControl1->ClientWidth / PageControl1->TabWidth;

}

void __fastcall TForm1::PageControl1Change(TObject *Sender)

{

  ScrollBar1->Position = ((TPageControl *)Sender)->ActivePage->PageIndex;

}

void __fastcall TForm1::ScrollBar1Scroll(TObject *Sender, TScrollCode ScrollCode, int &ScrollPos)

{

  PageControl1->ActivePage = PageControl1->Pages[ScrollPos];

}


OnSelectCell Example

The following code ensures that the user cannot select a cell unless it is empty.

void __fastcall TForm1::StringGrid1SelectCell(TObject *Sender, long Col, long Row, bool &CanSelect)

{

  CanSelect = (StringGrid1->Cells[Col][Row]== "")

}


OnShowHint Example

This example uses three speed buttons on a panel. The code changes the color, width, and position of the text in the Help Hint for the third speed button.  Set the ShowHint property of each speed button to true and give a value to the Hint property of each.

You must declare the DoShow method in the type declaration of the form. Once it is declared, write the code for the DoShow method in the implementation part of the unit. Finally, in the OnCreate event handler for the form, assign the method to the OnShowHint event of the application.

void __fastcall TForm1::DoShowHint(System::AnsiString &HintStr, bool &CanShow, THintInfo &HintInfo)

{

  if (HintInfo.HintControl == SpeedButton3)

  {

    HintInfo.HintColor = clAqua;// Changes only for this hint

    HintInfo.HintMaxWidth = 120; // Hint text word wraps if width is greater than 120

    HintInfo.HintPos.x += SpeedButton3->Width; // Move hint to right edge

  }

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->ShowHint = true;

  Application->OnShowHint = DoShowHint;

}


OpenLink, RequestData, DDEItem Example

The following code requests data if a link is open.

if (DdeClientConv1->OpenLink())

  DdeClientConv1->RequestData(DDEClientItem1->DdeItem);


Orientation Example

This example uses two radio buttons on a form named Landscape and Portrait. The form also includes a button. When the user selects an orientation by clicking one of the radio buttons and then clicks the button to print one line of text, the print job prints using the selected orientation:

void __fastcall TForm1::Button1Click(TObject Sender*)

{

  Printer()->BeginDoc();

  Printer()->Canvas->TextOut(100,100,"Hi there!");

  Printer()->EndDoc();

}

//---------------------------------------------------------------

void __fastcall TForm1::PortraitClick(TObject* Sender)

{

  Printer()->Orientation = poPortrait;

}

//---------------------------------------------------------------

void __fastcall TForm1::LandscapeClick(TObject* Sender)

{

  Printer()->Orientation = poLandscape;

}


TList::Pack Example

This example assumes there are two edit box controls on the form. The code creates a list object and adds two strings to it. The second string in the list is a null string. The code counts the number of strings in the list and displays the number in the Edit1 control. The code then packs the list, removing the null string, and counts the strings in the list again. The second count displays in the Edit2 control:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TList *MyList = new TList;

  MyList->Add("A string"); //Add a string

  MyList->Add(""); // Add an empty string

  MyList->Add(NULL); //Add NULL

  MyList->Add(""); // Add another empty string

  Edit1->Text = IntToStr(MyList->Count); // Put count into Edit1}

  MyList->Pack();                        // Pack the list.

  Edit2->Text = IntToStr(MyList->Count); // Put count into Edit2}

  delete MyList;  // Free memory for list

}


TPrinter::PageNumber Example

This example uses a button on a form. When the user clicks the button, one line of text is printed on six separate pages. As each page is printed, a message indicating the number of the page being printed appears on the status bar.

To run this example successfully, add  #include <Printers.h> to your unit and set the SimplePanel property of the status bar to true.

void __fastcall TForm1::Button1Click(TObject Sender*)

{

  Printer()->BeginDoc();

  for (int i = 1;i < 7;i++)

  {

    Printer()->Canvas->TextOut(100, 100, "C++Builder rules!");

    StatusBar1->SimpleText = AnsiString("Printing page ") + Printer()->PageNumber);

    Printer()->NewPage();

  }

  Printer()->EndDoc();

}


ParamByName, CreateParam Example

try

{

  // Assign a value of 999 to the CustNo parameter

  Query1->Params->ParamByName("CustNo")->AsInteger = 999;

}

catch (EDatabaseError &e) // if param doesn’t exist

{

  // Create a new parameter for CustNo

  // and assign a value of 999 to it

  TParam *newParam = Query1->Params->CreateParam(ftInteger, "CustNo", ptInput);

  newParam->AsInteger = 999;

}


ParamCount, DataType, StrToIntDef, AsXXX Example

This example fills in the parameters of a query from the entries of a list box.

for (int i = 0; i < Query1->ParamCount; i++)

{

  AnsiString ListItem = ListBox1->Items->Strings[i];

  TParam *pParam = Query1->Params->Items[i];

  switch (pParam->DataType)

  {

    case ftString:

        pParam->AsString = ListItem;

        break;

    case ftSmallint:

        pParam->AsSmallInt = StrToIntDef(ListItem, 0);

        break;

    case ftInteger:

        pParam->AsInteger = StrToIntDef(ListItem, 0);

        break;

    case ftWord:

        pParam->AsWord = StrToIntDef(ListItem, 0);

        break;

    case ftBoolean:

        if (ListItem == "True")

          pParam->AsBoolean = true;

        else

          pParam->AsBoolean = false;

        break;

    case ftFloat:

        pParam->AsFloat = StrToFloat(ListItem);

        break;

    case ftCurrency:

        pParam->AsCurrency = StrToFloat(ListItem);

        break;

    case ftBCD:

        pParam->AsBCD = StrToCurr(ListItem);

        break;

    case ftDate:

        pParam->AsDate = StrToDate(ListItem);

        break;

    case ftTime:

        pParam->AsTime = StrToTime(ListItem);

        break;

    case ftDateTime:

        pParam->AsDateTime = StrToDateTime(ListItem);

        break;

  }

}


ParamCount, Params, ParamType Example

// Set all input parameters to an empty string

for (int i = 0; i < StoredProc1->ParamCount; i++)

  if ((StoredProc1->Params->Items[i]->ParamType == ptInput)||

      (StoredProc1->Params->Items[i]->ParamType == ptInputOutput))

    StoredProc1->Params->Items[i]->AsString = "";


TQuery::Params Example

The following code runs an insert query to add a record for Lichtenstein into the country table.

Query2->SQL->Clear();

Query2->SQL->Add("INSERT INTO COUNTRY (NAME, CAPITAL, POPULATION) ");

Query2->SQL->Add("VALUES (:Name, :Capital, :Population) ");

Query2->Params->Items[0]->AsString = "Lichtenstein";

Query2->Params->Items[1]->AsString = "Vaduz";

Query2->Params->Items[2]->AsInteger = 420000;

Query2->ExecSQL();


Parent, GetNextChild, GetPrevChild Example

The following code tests to see if the currently selected item has a sibling. True will be assigned to HasSibling if so.

TTreeNode *SelNode = TTreeView1->Selected;

TTreeNode *ParentNode = SelNode->Parent;

bool HasSibling = (ParentNode->GetPrevChild(SelNode) ||

                   ParentNode->GetNextChild(SelNode));


Pause Example

This example uses a media player, a timer, and a button on a form. Only the button is visible when the application runs. When the user clicks the button, the .WAV file plays. When the user clicks the button again, the .WAV file pauses. The caption of the button changes, depending on whether the .WAV file is playing, paused, or stopped.

To run this example, you must have the CHIMES.WAV file in your Windows directory and install a device that plays WAV audio files:

void __fastcall TForm1::FormActivate(TObject *Sender)

{

  char WinDir[144];

  MediaPlayer1->Visible = false;

  GetWindowsDirectory(WinDir, sizeof(WinDir));

  strcat(WinDir, "\chimes.wav");

  MediaPlayer1->FileName = AnsiString(WinDir);

  MediaPlayer1->Open();

  Button1->Caption = "Play";

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (Button1->Caption == "Play")

  {

    Button1->Caption = "Pause";

    MediaPlayer1->Play();

  }

  else

  {

    Button1->Caption = "Play";

    MediaPlayer1->Pause();

  }

}

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  if (MediaPlayer1->Mode == mpStopped)

    Button1->Caption = "Play";

}


PauseOnly Example

The following code illustrates the difference between Pause and PauseOnly. After the second call to Pause, MediaPlayer1 resumes playing. After the second call to PauseOnly, MediaPlayer1 is still paused.

MediaPlayer1->Play();

MediaPlayer1->Pause();

// Now its paused

MediaPlayer1->Pause();

// Now its playing – the Pause property toggled

MediaPlayer1->PauseOnly();

// Now its paused again

MediaPlayer1->PauseOnly();

// Now its still paused


Pixels Example

This example draws a red line (very slowly) when the user presses a button. Attach the following code to the OnClick event handler:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for (int i = 10; i <= 200; i++)

    Canvas->Pixels[i][10] = clRed;

}


 PokeData Example

The following code pokes the data that is in Edit1 to the DDE server. The DDE item of the conversation is specified in the DDEItem property of DDEClientItem1.

DdeClientConv1->PokeData(DdeClientItem1->DdeItem, Edit1->Text.c_str());


 PokeDataLines Example

The following code pokes the data that is in Memo1 to the DDE server. The DDE item of the conversation is specified in the DDEItem property of DDEClientItem1.

DDEClientConv1->PokeDataLines(DdeClientItem1->DdeItem, Memo1->Lines);


OnPaint, Pen, Polyline Example

This example paints a white five pointed star in a paintbox control:

void __fastcall TForm1::PaintBox1Paint(TObject *Sender)

{

  TPaintBox *pPB = (TPaintBox *)Sender;

  POINT points[6];

  pPB->Canvas->Pen->Color = clWhite;

  points[0].x = 40;

  points[0].y = 10;

  points[1].x = 20;

  points[1].y = 60;

  points[2].x = 70;

  points[2].y = 30;

  points[3].x = 10;

  points[3].y = 30;

  points[4].x = 60;

  points[4].y = 60;

  points[5].x = 40;

  points[5].y = 10;

  pPB->Canvas->Polyline(points,5);

}


Popup, AutoPopup Example

This example uses a pop-up menu. When the user presses the mouse button, the pop-up menu appears where the user clicked the mouse:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  PopupMenu1->AutoPopup = false;

}

void __fastcall TForm1::FormMouseDown(TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y)

{

  PopupMenu1->Popup(X, Y);

}


PopupComponent, PopupMenu Example

This example uses two edit boxes, two memos, and one pop-up menu on a form. The pop-up menu contains Cut, Copy, and Paste commands. This code makes the pop-up menu available to both edit boxes and both memos:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  PopupMenu1->AutoPopup = true;

  Edit1->PopupMenu = PopupMenu1;

  Edit2->PopupMenu = PopupMenu1;

  Memo1->PopupMenu = PopupMenu1;

  Memo2->PopupMenu = PopupMenu1;

}

These are the cut, copy, and paste OnClick events for the commands on the pop-up menu.

void __fastcall TForm1::Copy1Click(TObject *Sender)

{

  TComponent *pComponent = PopupMenu1->PopupComponent;

  if (pComponent)

  {

    if (pComponent->ClassNameIs("TEdit"))

      ((TEdit *)pComponent)->CopyToClipboard();

    else if (pComponent->ClassNameIs("TMemo"))

      ((TMemo *)pComponent)->CopyToClipboard();

    else

      MessageBeep(0);

  }

  else

    MessageBeep(0);

}

void __fastcall TForm1::Cut1Click(TObject *Sender)

{

  TComponent *pComponent = PopupMenu1->PopupComponent;

  if (pComponent)

  {

    if (pComponent->ClassNameIs("TEdit"))

      ((TEdit *)pComponent)->CutToClipboard();

    else if (pComponent->ClassNameIs("TMemo"))

      ((TMemo *)pComponent)->CutToClipboard();

    else

      MessageBeep(0);

  }

  else

    MessageBeep(0);

}

void __fastcall TForm1::Paste1Click(TObject *Sender)

{

  TComponent *pComponent = PopupMenu1->PopupComponent;

  if (pComponent)

  {

    if (pComponent->ClassNameIs("TEdit"))

      ((TEdit *)pComponent)->PasteFromClipboard();

    else if (pComponent->ClassNameIs("TMemo"))

      ((TMemo *)pComponent)->PasteFromClipboard();

    else

      MessageBeep(0);

  }

  else

    MessageBeep(0);

}


Prepared, Prepare Example

if(!Query1->Prepared)

{

  Query1->Close();

  Query1->Prepare();

  Query1->Open();

}


Parent, Top, Left, Checked, Preview Example

This example uses a report component, a radio group, two radio buttons, and a button on a form. When the user clicks the button, the report is sent to the screen if the screen radio button is selected, and to the printer if the printer radio button is selected.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  RadioGroup1->Caption = "Send Report";

  RadioButton1->Parent = RadioGroup1;

  RadioButton1->Caption = "to Printer";

  RadioButton1->Top = 15;

  RadioButton1->Left = 10;

  RadioButton1->Checked = true; // initialize to printer

  RadioButton2->Parent = RadioGroup1;

  RadioButton2->Caption = "to Screen";

  RadioButton2->Top = 35;

  RadioButton2->Left = 10;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Report1->ReportName = "MyReport";

  Report1->Preview = !RadioButton1->Checked;

  Report1->Run();

}


PrintToFile, SaveToFile, SaveDialog Example

This example displays a print dialog box with a Print to File check box, and then prints the contents of a rich edit control to the indicated destination:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  PrintDialog1->Options << poPrintToFile;

  PrintDialog1->PrintToFile = true;

  if (PrintDialog1->Execute())

  {

    if (PrintDialog1->PrintToFile)

    {

      SaveDialog1->Title = "Print to File:";

      if (SaveDialog1->Execute())

        RichEdit1->Lines->SaveToFile(SaveDialog1->FileName);

      else

        RichEdit1->Print("");

    }

  }

}


ProcessMessages Example

This example uses two buttons that are long enough to accommodate lengthy captions on a form. When the user clicks the button with the caption Ignore Messages, the code begins to generate a long series of random numbers. If the user tries to resize the form while the handler is running, nothing happens until the handler is finished. When the user clicks the button with the caption Process Messages, more random numbers are generated, but Windows can still respond to a series of mouse events, such as resizing the form.

Note:	How quickly these event handlers run depends on the microprocessor of your computer. A message appears on the form informing you when the handler has finished executing.

void __fastcall TForm1::FormCreate(TObject* Sender)

{

  Button3->Caption = "Ignore Messages";

  Button3->Caption = "Handle Message";

}

void __fastcall TForm1::Button1Click(TObject* Sender)

{

  int x, y;

  for (int i = 0; i < 64000; i++)

 {

    Randomize();

    for (int j = 0; j < 64000; j++)

      y = random(j);

    x = random(i);

  }

  Canvas->TextOut(10, 10, "The Button1Click handler is finished");

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

  int x, y;

  for (int i = 0; i < 64000; i++)

  {

    Randomize();

    for (int j = 0; j < 64000; j++)

    {

      y = random(j);

      Application->ProcessMessages();

    }

    x = random(i);

  }

  Canvas->TextOut(10, 10, "The Button2Click handler is finished");

}


TBlobStream::Read Example

The following example reads reads the data from a memo field into a blob stream and displays it in a memo control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int MemSize;

  char *Buffer;

  TBlobStream *Stream;

  if (!Query1->Eof)

    Query1->Next();

  Stream = new TBlobStream((TBlobField *)Query1->FieldByName("Notes"), bmRead);

  try

  {

    MemSize = Stream->Size + 1; // add one for null terminator

    Buffer = new char[MemSize]; // Allocate the memory.

    try

    {

      Stream->Read(Buffer, MemSize); //Read Notes field into buffer.

      Memo1->SetTextBuf(Buffer);  // Display the buffer's contents.

    }

    catch (...)

    {

      delete Buffer;

      throw;

    }

    delete Buffer;

  }

  catch (...)

  {

    delete Stream;

    throw;

  }

  delete Stream;

}


ReadBool, ReadInteger, ReadString Example

This example reads the DELPHI.INI file and displays on the form the status of your auto save options.

Before you run this example, you must include IniFiles.hpp in your unit.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TIniFile *pIniFile = new TIniFile("c:\MyApp\bin\MyApp.ini");

  if (pIniFile->ReadBool("AutoLoad", "FormProperties", false) == true)

  {

    Visible = pIniFile->ReadBool("FormOptions", "Visible", true);

    Color = (Graphics::TColor)pIniFile->ReadInteger("FormOptions", "Color", clWindow);

    Caption = pIniFile->ReadString("FormOptions", "Caption", "Main");

  }

  delete pIniFile;

}


ReadSectionValues, WriteString, DeleteKey Example

This example reads the Desktop section of the WIN.INI file into a memo and changes one of the strings in the INI file when Button1 is clicked.  When Button2 is clicked, the WIN.INI file is restored to its initial state, using the values stored in the memo.

Before you run this example, you must add #include <IniFiles.hpp> to your unit file.

Warning

Do not click button2 before you have clicked button1!

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TIniFile *pWinIni = new TIniFile("c:\Windows\Win.ini");

  Memo1->Clear();

  pWinIni->ReadSectionValues("Desktop", Memo1->Lines);

  if (Memo1->Lines->Values["Pattern"] != "(None)")

    pWinIni->WriteString("Desktop","Pattern","(None)");

  delete pWinIni;

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

  TIniFile *pWinIni = new TIniFile("c:\Windows\Win.ini");

  // if the entry wasn’t there before, delete it now

  if (Memo1->Lines->Values["Pattern"] == "")

    pWinIni->DeleteKey("Desktop", "Pattern");

  // otherwise, restore the old value

  else

    pWinIni->WriteString("Desktop", "Pattern",

                         Memo1->Lines->Values["Pattern"]);

  delete pWinIni;

}


Rectangle, Style, Color Example

This example draws many rectangles of various sizes and colors on a form maximized to fill the entire screen.  To run the code, drop a TTimer component on the form and use the object inspector to create the OnTimer event.

int x, y;

//----------------------------------------------------------

void __fastcall TForm1::FormActivate(TObject *Sender)

{

  WindowState = wsMaximized;

  Timer1->Interval = 50;

  randomize();

}

//-----------------------------------------------------------

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  x = random(Screen->Width - 10);

  y = random(Screen->Height - 10);

  Canvas->Pen->Color = (Graphics::TColor) random(65535);

  switch (random(5))

  {

    case 0: Canvas->Pen->Style = psSolid; break;

    case 1: Canvas->Pen->Style = psDash; break;

    case 2: Canvas->Pen->Style = psDot; break;

    case 3: Canvas->Pen->Style = psDashDot; break;

    case 4: Canvas->Pen->Style = psDashDotDot; break;

  }

  Canvas->Rectangle(x, y, x + random(400), y + random(400));

}


Remove Example

The following code adds a new object to a list in a list object and then removes it:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TList *pList = new TList();

  AnsiString TheObject = "This is an object."

  try

  {

    pList->Add(TheObject); // add AnsiString instance to list

    MessageDlg("The list has " + IntToStr(pList->Count) + "objects",

               mtInformation, TMsgDlgButtons() << mbOK, 0);

    pList->Remove(TheObject);

    MessageDlg("The list has " + IntToStr(pList->Count) + "objects",

               mtInformation, TMsgDlgButtons() << mbOK, 0);

  }

  catch (...)

  {

    delete pList;

    throw;

  }

  delete pList;

}


OnMinimize, Restore Example

This example uses a timer on a form. When the application runs and the user minimizes the application, the timer starts and the application returns to its normal size when an OnTimer event occurs.  The timer then shuts down until the next time the form is minimized.

Be sure to declare the AppStartTimer method as a public method of TForm1.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->OnMinimize = AppStartTimer;

  Timer1->Interval = 1000;

}

void __fastcall TForm1::AppStartTimer(TObject *Sender)

{

  Timer1->Enabled = true;

}

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  Application->Restore();

  Timer1->Enabled = false;

}


Rewind Example

This example uses a media player and a button on a form. When the user clicks the button, the WAV audio media rewinds and begins playing. To run this example successfully, you must have installed a WAV audio device correctly.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  MediaPlayer1->DeviceType = dtWaveAudio;

  MediaPlayer1->AutoRewind = false;

  MediaPlayer1->FileName = "CHIMES.WAV";

  Button1->Caption = "Rewind and Play";

  Button1->Width = 130;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  MediaPlayer1->Rewind();

  MediaPlayer1->Play();

}


RoundRect, Width Example

This example draws many rectangles of various sizes and colors on a form maximized to fill the entire screen:

int x, y;

//----------------------------------------------------------

void __fastcall TForm1::FormActivate(TObject *Sender)

{

  WindowState = wsMaximized;

  Timer1->Interval = 50;

  randomize();

}

//-----------------------------------------------------------

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

  x = random(Screen->Width - 10);

  y = random(Screen->Height - 10);

  Canvas->Pen->Color = (Graphics::TColor) random(65535);

  Canvas->Pen->Width = random(7);

  Canvas->RoundRect(x, y, x + random(400), y + random(400));

}


Row, Rows Example

This example displays a string grid, a list box, and a button on a form. When the application runs, strings are put in the cells of row 1 of the string grid. When the user clicks the button, The strings in the current row of the grid are displayed in the list box.

Note that when the grid contains an empty cell, the list box has a corresponding empty string.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items = StringGrid1->Rows[StringGrid1->Row];

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  StringGrid1->Cells[1][0] = "Column 1";

  StringGrid1->Cells[2][0] = "Column 2";

  StringGrid1->Cells[3][0] = "Column 3";

  StringGrid1->Cells[4][0] = "Column 4";

  StringGrid1->Cells[0][1] = "Row 1";

  StringGrid1->Cells[1][1] = "C++";

  StringGrid1->Cells[2][1] = "Builder";

  StringGrid1->Cells[3][1] = "is";

  StringGrid1->Cells[4][1] = "RAD";

  StringGrid1->Cells[0][2] = "Row 2";

  StringGrid1->Cells[1][2] = "Rapid";

  StringGrid1->Cells[2][2] = "Application";

  StringGrid1->Cells[4][2] = "Development";

}


State, Seek, Truncate Example

The following example deletes the stream from position 60 within the blob stream to the end.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TBlobStream *Stream1 = new TBlobStream(Table1Notes, bmReadWrite);

  try

  {

    Table1->Edit();

    if (Table1->State == dsEdit)

    {

      Stream1->Seek(60, 0); // Move to byte #60

      Stream1->Truncate();  /* Delete from current position (60) to end of stream. */

      Table1->Post();

    }

  }

  catch (...)

  {

    delete Stream1;

    throw;

  }

  delete Stream1;


TParam::SetData Example

long I = Table1->FieldByName("CustID")->AsInteger;

// Set the data

Query1->ParamByName("CustNo")->SetData(&I);


TField::SetData Example

// Assign "raw" data to Field1

// Allocate space

void *buffer = malloc(Field1->DataSize);

// Fill buffer with the desired data

...

// Then do the assignment

Field1->SetData(buffer)

// Free the space

free(buffer);


 SetLink, DdeService, DdeTopic Example

The following code establishes a link with a DDE server. The service is specified in the DdeService property of DdeClientConv1, and the topic is specified in the DdeTopic property of DdeClientConv1. If the link is not established, an exception is thrown.

// define the exception class

class DdeLinkFailure

{

  public:

    char msg[256];

    DdeLinkFailure(char *pStr) {strcpy(msg,pStr); }

    DdeLinkFailure(DdeLinkFailure &f) {strcpy(msg, f.msg);}

};

// later, try to establish the connection

// and throw the exception if this fails

DdeClientConv1->DdeService = "ReportSmith";

DdeClientConv1->DdeTopic = "RS_PrintReport";

if (!DdeClientConv1->SetLink(DdeClientConv1->DdeService, DdeClientConv1->DdeTopic))

  throw DdeLinkFailure("Could not link to DDE server.");


SetRangeStart, SetRangeEnd Example

Table1->SetRangeStart(); // Set the beginning key

Table1->FieldByName("City")->AsString = "San Jose";

Table1->SetRangeEnd(); // Set the ending key

Table1->FieldByName("City")->AsString = "Scotts Valley";

Table1->ApplyRange(); // Tell the dataset to establish the range


ShowAccelChar Example

This example uses two labels on a form. The first label has a caption with an accelerator character in it. The second label also includes an ampersand, but it does not appear as an accelerator character.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Label1->ShowAccelChar = true;

  Label1->Caption = "An &Underlined character appears here";

  Label2->ShowAccelChar = false;

  Label2->Caption = "An ampersand (&) appears here";

}


TListBox::Sorted Example

This example uses an edit box, a list box, and two buttons on a form. The buttons are named Add and Sort. When the user clicks the Add button, the text in the edit box is added to the list in the list box. Before the user clicks the sort button, any new items are added to the end of the list.  After the user clicks the Sort button, the list in the list box is sorted and remains sorted, even if additional strings are added.  If the user clicks the sort button again, the list box remains sorted, but any new strings are again added to the end of the list.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  ListBox1->Items->Add("Not");

  ListBox1->Items->Add("In");

  ListBox1->Items->Add("Alphabetical");

  ListBox1->Items->Add("Order");

}

void __fastcall TForm1::AddClick(TObject *Sender)

{

  ListBox1->Items->Add(Edit1->Text);

}

void __fastcall TForm1::SortClick(TObject *Sender)

{

  ListBox1->Sorted = !ListBox1->Sorted;

}


TStringList::Sorted Example

This example uses a list box on a form. When the application runs, a string list object is created and three strings are added to it. The strings are sorted and added to the list box, where they appear in their sorted order:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TStringList *pList = new TStringList();

  pList->Add("Plants");

  pList->Add("Animals");

  pList->Add("Minerals");

  pList->Sorted = true;

  ListBox1->Items->AddStrings(pList);

  delete pList;

}


TDataSource::State Example

The following code enables a post button only when the data set is edited.

if (DataSource1->Dataset)

  PostButton->Enabled = (DataSource1->State == dsEdit || DataSource1->State == dsInsert);


 TimeFormat, Length Example

The following code declares a HMSRec record with four byte fields. If TimeFormat is tfHMS, the first field specifies hours, the second field specifies minutes, the third field specifies seconds, and the fourth field corresponds to the unused most-significant byte of the tfHMS time format. A LongInt variable is typecast to an HMSRec record, then the hours, minutes, and seconds of the Length of the loaded media are displayed in labels when the user clicks a button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int TheLength;

// Set time format - note that some devices don’t support tfHMS }

  MediaPlayer1->TimeFormat = tfHMS;

  // Store length of currently loaded media

  TheLength = MediaPlayer1->Length;

  // display hours in label 1

  Label1->Caption = IntToStr(LOBYTE(LOWORD(TheLength)));

  // display minutes in label 2

  Label2->Caption = IntToStr(HIBYTE(LOWORD(TheLength)));

  // display the seconds in label 3

  Label3->Caption = IntToStr(LOBYTE(HIWORD(TheLength)));

}


Metafile Example

This example shows how to create or augment a metafile using a metafile canvas object.  This metafile can then be used to draw on the canvas of another object such as a paintbox or a printer.

TMetafile *pMetafile = new TMetafile;

TMetafileCanvas *pCanvas = new TMetafileCanvas(pMetafile, 0);

pCanvas->Brush->Color = clRed;

pCanvas->Ellipse(0,0,100,100);

// ...

delete pCanvas;

Form1->Canvas->Draw(0,0,pMetafile); //1 red circle

To add to an existing metafile image, create a metafile canvas and play the source metafile into the metafile canvas:

TMetafileCanvas *pCanvas = new TMetafileCanvas(pMetafile, 0);

pCanvas->Draw(0,0,pMetafile);

pCanvas->Brush->Color = clBlue;

pCanvas->Ellipse(100,100,200,200);

// ...

delete pCanvas;

Form1->Canvas->Draw(0,0,pMetafile); // 1 red circle and 1 blue circle

// ...

delete pMetafile;


TDirectoryListBox::Update Example

The following sample code sets the directory of DirectoryListBox1 to C:\TEMP when the form is created. When Button1 is pressed, a subdirectory called MYDIR is added to C:\TEMP, but note that it is not updated in DirectoryListBox1 until Button2 is pressed and Update is called.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ForceDirectories("c:\temp\mydir");

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  DirectoryListBox1->Directory = "c:\temp";

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

  DirectoryListBox1->Update();

}


Sessions, GetSessionNames, SessionName, ValidateName Example

The following example searches all sessions for an open session with the BCDEMOS directory.

AnsiString __fastcall TForm1::IsDuplicate(AnsiString DBName)

{

  TStringList *SessionNames = new TStringList();

  AnsiString Result = "";

  try

  {

    Sessions->GetSessionNames(SessionNames);

    for (int SessionCount= 0;

             SessionCount < Sessions->Count;

             SessionCount++)

    {

      TDatabase *pDB = new TDatabase(NULL);

      try

      {

        pDB->SessionName = SessionNames->Strings[SessionCount];

        try

        {

          pDB->ValidateName(DBName);

        }

        catch (EDatabaseError &e)

        {

          Result = SessionNames->Strings[SessionCount];

        }

      }

      catch (...)

      {

        delete pDB;

        throw;

      }

      delete pDB;

      if (!Result.IsEmpty())

        break;

    }

  }

  catch (...)

  {

    delete SessionNames;

    throw;

  }

  delete SessionNames;

  return Result;

}

void __fastcall TForm1::Button1Click(TObject *Sender TObject)

{

  AnsiString Duplicate = IsDuplicate("c:\Program Files\Borland\CBuilder\Examples\Data");

  if (!Duplicate.IsEmpty())

    ShowMessage("Duplicate found in " + Duplicate + " Session");

  else

    ShowMessage("Not A Duplicate");

}


TSessionList::Sessions, TSessionList::Count Example

The following code sets the KeepConnections property of each session to False:

for (int i = 0; i < Sessions->Count; i++)

  Sessions->Sessions[i]->KeepConnections = false;


TDBRadioGroup::Items, TDBRadioGroup::Values Example

This example uses a database radio group box connected to field in a dataset. The field contains the values "Y", "N", or "M". In contrast, the user sees the captions of the radio buttons to be "Yes", "No", or "Maybe".

When the code runs, three radio buttons appear in the group box. If the current record in the dataset contains any of the values contained in the Values property, the appropriate radio button is checked. When the user selects a radio button, the corresponding string in the Values property is entered into the field.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  DBRadioGroup1->Items->Add("Yes");

  DBRadioGroup1->Items->Add("No");

  DBRadioGroup1->Items->Add("Maybe");

  DBRadioGroup1->Values->Add("Y");

  DBRadioGroup1->Values->Add("N");

  DBRadioGroup1->Values->Add("M");

}


TMediaPlayer::Wait Example

The following code plays a .WAV audio file named NI!.WAV twice. The first call to play doesn't return control to the application until the file is done playing. Note that if you remove the line of code that sets wait to true, the sound is only played once.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  MediaPlayer1->FileName = "ni!.wav";

  MediaPlayer1->AutoRewind = true;

  MediaPlayer1->Open(); // Open the media player

  try

  {

    MediaPlayer1->Wait = true; // Waits until sounds is done playing to return

    MediaPlayer1->Play();      // Play sound

   MediaPlayer1->Play();      // Play again after first play is completed

  }

  catch (...)

  {

    MediaPlayer1->Close();   // Close media player

    throw;

  }

  MediaPlayer1->Close();

}


TBlobStream::Write Example

The following example writes a string to the end of a blob stream.

void __fastcall TForm1::Button3Click(TObject *Sender)

{

  TBlobStream *pStream;

  Table1->Edit();

  if (Table1->State == dsEdit)

  {

    pStream = Table1->CreateBlobStream(Table1->FieldByName("Notes"), bmReadWrite);

    try

    {

      AnsiString S = "This line will be added to the end";

      pStream->Seek(0, 2); // Seek 0 bytes from the stream's end point

      pStream->Write(S.c_str(), S.Length());

      Table1->Post();

    }

    catch (...)

    {

      delete pStream;

      throw;

    }

    delete pStream;

  }

}


WriteBool, WriteInteger Example

This example creates an .INI file for a game with two entries in the Options section, and one entry in the Configuration section.

Before you try this example, you must add #include <IniFiles.hpp> to your unit file.

TIniFile *GameIni = new TIniFile ("FUNGAME.INI");

GameIni->WriteBool("Options", "Sound", true);

GameIni->WriteInteger("Options", "Level", 3);

GameIni->WriteBool("Configuration", "ShowToolBar", false);

delete GameIni;


ClientDataSet::IndexDefs, ClientDataSet::IndexName Example

This example uses the IndexName property to sort the records in a client dataset on the CustNo and OrderNo fields.

// Get the current available indicies

ClientDataSet1->IndexDefs->Update();

/* Find one which combines Customer Number ("CustNo") and Order Number ("OrderNo") }

for (int I = 0; I < ClientDataSet1->IndexDefs->Count; I++)

  if (ClientDataSet1->IndexDefs->Items[I]->Fields == String("CustNo;OrderNo"))

  {

    // set that index as the current index for the table

    ClientDataSet1->IndexName = ClientDataSet1->IndexDefs->Items[I]->Name;

  }


IndexFields, IndexFieldCount Example

int TotalLen = 0;

// Calculate the total length of the index

for (int I = 0; I < ClientDataSet1->IndexFieldCount; I++)

  TotalLen += ClientDataSet1->IndexFields[I]->DataSize;


SetRangeStart, SetRangeEnd, ApplyRange Example

ClientDataSet1->SetRangeStart(); // Set the beginning key

ClientDataSet1->FieldByName("City")->AsString = "San Jose";

ClientDataSet1->SetRangeEnd(); // Set the ending key

ClientDataSet1->FieldByName("City")->AsString = "Scotts Valley";

ClientDataSet1->ApplyRange(); // Tell the dataset to establish the range


Columns, Items, BgColor Example

The following example colors every other column in the HTML table produced by a TDataSetTableProducer gray:

for (int i = 0; i < DataSetTableProducer1->Columns->Count; i++)

{

  if (i % 2 == 0)

    DataSetTableProducer1->Columns->Items[I]->BgColor = "White";

  else

    DataSetTableProducer1->Columns->Items[I]->BgColor = "Gray";

}


 Topic Not Found

The topic you are looking for was not found. It may be inaccessible using your current search method. To determine if a topic is missing, try using one of the alternative search methods described below. If you do not find the topic, it may be missing from the help files. Visit the Borland web site at www.borland.com to see if updated help files are available.

You can search for topics in several ways:

1	Press F1 on a property or event name in the Object Inspector.

2	Press F1 on a property, event, method, function, procedure, or type in the Code editor.

3	Click the Contents tab to browse through topics by category.

4	Click the Index tab to see a list of index entries.

5	Click the Find tab to search for words or phrases


AnsiString

Methods	Example

Header

vcl/dstring.h

Description

C++Builder implements the AnsiString type as a class. AnsiString is designed to function like the Delphi long  string type. Accordingly, AnsiString provides the following string handling characteristics which are required when you call VCL-type functions that use any of the Delphi long string types.

•	reference count

•	string length

•	data

•	null string terminator

If you don’t provide an initial value, AnsiString variables are initialized to zero upon instantiation.


AnsiString methods

AnsiString	Alphabetically

In AnsiString

~AnsiString

AnsiCompare

AnsiCompareIC

AnsiLastChar

AnsiPos

AnsiString

ByteType

c_str

CurrToStr

CurrToStrF

Delete

FloatToStrF

FmtLoadStr

Format

FormatFloat

Insert

IntToHex

IntToHex

IsDelimiter

IsEmpty

IsLeadByte

IsPathDelimiter

IsTrailByte

LastDelimiter

Length

LoadStr

LowerCase

operator !=

operator []

operator +

operator +=

operator <

operator <=

operator =

operator ==

operator >

operator >=

Pos

SetLength

StringOfChar

SubString

ToDouble

ToInt

ToIntDef

Trim

TrimLeft

TrimRight

TStringMbcsByteType

Unique

UpperCase

WideChar

WideCharBufSize


AnsiString methods

AnsiString	By object

~AnsiString

AnsiCompare

AnsiCompareIC

AnsiLastChar

AnsiPos

AnsiString

ByteType

c_str

CurrToStr

CurrToStr

CurrToStrF

CurrToStrF

Delete

FloatToStrF

FmtLoadStr

Format

FormatFloat

Insert

IntToHex

IsDelimiter

IsEmpty

IsLeadByte

IsPathDelimiter

IsTrailByte

LastDelimiter

Length

LoadStr

LowerCase

operator !=

operator []

operator +=

operator +

operator <=

operator ==

operator =

operator >=

operator >

Pos

SetLength

StringOfChar

SubString

ToDouble

ToInt

ToIntDef

Trim

TrimLeft

TrimRight

TStringMbcsByteType

Unique

UpperCase

WideChar

WideCharBufSize


AnsiString::AnsiString

AnsiString

Description

The constructor for AnsiString is overloaded as follows:

__fastcall AnsiString();

Creates an empty string.

__fastcall AnsiString(const char* src);

Creates a null-terminated string from a character array.

__fastcall AnsiString(const AnsiString& src);

(Copy constructor.) Creates a copy of an AnsiString.

__fastcall AnsiString(const char* src, unsigned char len);

Creates a null-terminated string that is a copy of the first len characters of src. For example, if src contains the character string “Hello” and len is 2, then the AnsiString that is created would contain the null-terminated string “He”.

__fastcall AnsiString(const wchar_t* src);

Creates a null-terminated string from a wide character array.

__fastcall AnsiString(int src);

Creates a null-terminated string from an int. The string contains the string representation of the int value given by src.

__fastcall AnsiString(double src);

Creates a null-terminated string from a double. The string contains the string representation of the floating-point value given by src. The conversion uses general number format with 15 significant digits.


AnsiString::~AnsiString

AnsiString

Description

~AnsiString is the destructor of an AnsiString object.

__fastcall ~AnsiString();

~AnsiString clears the string.


AnsiString::FloatToStrF

AnsiString

Description

FloatToStrF converts a floating-point value to its string representation.

static AnsiString __fastcall FloatToStrF(long double value, TStringFloatFormat format, int precision, int digits);

The format parameter controls the format of the resulting string. The precision parameter specifies the precision of the given value. It should be 7 or less for values of type float, 15 or less for values of type double, and 18 or less for values of type Extended. The meaning of the digits parameter depends on the particular format selected.

The format parameter is of type TStringFloatFormat.

enum TStringFloatFormat {sffGeneral, sffExponent, sffFixed, sffNumber, sffCurrency };

The possible values of the format parameter, and the meaning of each, are described below.

Value	Meaning

sffGeneral 	General number format. The value is converted to the shortest possible decimal string using fixed or scientific format. Trailing zeros are removed from the resulting string, and a decimal point appears only if necessary. The resulting string uses fixed point format if the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, and if the value is greater than or equal to 0.00001. Otherwise the resulting string uses scientific format, and the digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).

sffExponent	Scientific format. The value is converted to a string of the form "-d.ddd...E+dddd". The resulting string starts with a minus sign if the number is negative, and one digit always precedes the decimal point. The total number of digits in the resulting string (including the one before the decimal point) is given by the precision parameter. The "E" exponent character in the resulting string is always followed by a plus or minus sign and up to four digits. The digits parameter specifies the minimum number of digits in the exponent (between 0 and 4).

sffFixed	Fixed point format. The value is converted to a string of the form "-ddd.ddd...". The resulting string starts with a minus sign if the number is negative, and at least one digit always precedes the decimal point. The number of digits after the decimal point is given by the digits parameter--it must be between 0 and 18. If the number of digits to the left of the decimal point is greater than the specified precision, the resulting value will use scientific format.

sffNumber	Number format. The value is converted to a string of the form "-d,ddd,ddd.ddd...". The sffNumber format corresponds to the sffFixed format, except that the resulting string contains thousand separators.

sffCurrency	Currency format. The value is converted to a string that represents a currency amount. The conversion is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator, and DecimalSeparator global variables, all of which are initialized from the Currency Format in the International section of the Windows Control Panels. The number of digits after the decimal point is given by the Digits parameter--it must be between 0 and 18.

For all formats, the actual characters used as decimal and thousand separators are obtained from the DecimalSeparator and ThousandSeparator global variables.

If the given value is a NAN (not-a-number), the resulting string is 'NAN'. If the given value is positive infinity, the resulting string is 'INF'. If the given value is negative infinity, the resulting string is '-INF'.


AnsiString::operator +

AnsiString

Description

Concatenates two AnsiStrings.

friend AsiString __fastcall operator +(const char* lhs, const AnsiString& rhs);

Returns an AnsiString that is the concatenation of strings lhs and rhs.

AnsiString __fastcall operator +(const AnsiString& rhs) const;

Returns an AnsiString that is the concatenation of this AnsiString and rhs.


AnsiString::StringOfChar

AnsiString

Description

Returns a string with the specified number of characters.

static AnsiString __fastcall StringOfChar(char ch, int count);

Returns a string containing count characters with the character value given by ch. For example,

AnsiString s = AnsiString::StringOfChar('A', 10);

sets s to the string 'AAAAAAAAAA'.


AnsiString::LoadStr

AnsiString

Description

Loads a string from the application's executable file.

static AnsiString __fastcall LoadStr(int ident);

Loads the string resource given by ident from the application's executable file. If the string resource does not exist, an empty string is returned.

Moving display strings into string resources makes an application easier to localize without rewriting the program.


AnsiString::FmtLoadStr

AnsiString

Description

Formats output using a resourced format string.

static AnsiString __fastcall FmtLoadStr(int ident, const TVarRec *args, int size);

Loads a string from a program's resource string table and uses that string, plus the args array, as a parameter to Format. Ident is the string resource ID of the desired format string.


AnsiString::Format

AnsiString

Description

Formats a string assembled from an AnsiString, format, and a series of array arguments, args.

static AnsiString __fastcall Format(const AnsiString& format,const TVarRec *args, int size);


AnsiString::FormatFloat

AnsiString

Description

Formats the floating-point value given by value using the format string given by format.

static AnsiString __fastcall FormatFloat(const AnsiString& format,const long double& value);

The following format specifiers are supported in the format string:

Specifier	Represents

0	Digit place holder. If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the output string. Otherwise, a '0' is stored in that position in the output string.

#	Digit placeholder. If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.

.	Decimal point. The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored. The actual character used as a the decimal separator in the output string is determined by the DecimalSeparator global variable. The default value of DecimalSeparator is specified in the Number Format of the International section in the Windows Control Panel.

,	Thousand separator. If the format string contains one or more ',' characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of ',' characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is determined by the ThousandSeparator global variable. The default value of ThousandSeparator is specified in the Number Format of the International section in the Windows Control Panel.

E+	Scientific notation. If any of the strings 'E+', 'E-', 'e+', or 'e-' are contained in the format string, the number is formatted using scientific notation. A group of up to four '0' characters can immediately follow the 'E+', 'E-', 'e+', or 'e-' to determine the minimum number of digits in the exponent. The 'E+' and 'e+' formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The 'E-' and 'e-' formats output a sign character only for negative exponents.

'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting.

;	Separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost '0' before the decimal point in the format string and the rightmost '0' after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ('0' or '#') to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the '.' character in the format string, the extra digits are output before the first digit placeholder.

To allow different formats for positive, negative, and zero values, the format string can contain from one to three sections separated by semicolons.

•	One section: The format string applies to all values.

•	Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

•	Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If no formatting is specified for positive values, positive values are formatted using general floating-point formatting with 15 significant digits, corresponding to a call to FloatToStrF with the sffGeneral format. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.

The following table shows some sample formats and the results produced when the formats are applied to different values:

Format string-	1234	-1234	0.5	0

1234	-1234	0.5	0

0	1234	-1234	1	0

0.00 	1234.00	-1234.00	0.50	0.00

#.##  	1234	-1234	.5

#,##0.00	1,234.00	-1,234.00	0.50	0.00

#,##0.00;(#,##0.00)	1,234.00	(1,234.00)	0.50	0.00

#,##0.00;;Zero 	1,234.00	-1,234.00	0.50	Zero

0.000E+00   	1.234E+03	-1.234E+03	5.000E-01	0.000E+00

#.###E-0  	1.234E3	-1.234E3	5E-1	0E0


AnsiString::IntToHex

AnsiString

Description

Converts a number into a string containing the number's hexadecimal (base 16) representation.

static AnsiString __fastcall IntToHex(int value, int digits);

Value is the number to convert. Digits indicates the minimum number of hexadecimal digits.


AnsiString::CurrToStr

AnsiString	See also

Description

Converts a currency value to its string representation.

static AnsiString __fastcall CurrToStr(Currency value);

CurrToStr converts the currency value given by value to its string representation. The conversion using the sffGeneral floating-point conversion rules. For further details, see CurrToStrF.


AnsiString::CurrToStrF

AnsiString

Description

Converts a currency value to its string representation using the indicated float format convention.

static AnsiString __fastcall CurrToStrF(Currency value, TStringFloatFormat format, int digits);

Converts the currency value given by value to its string representation using the indicated float format convention. A call to CurrToStrF corresponds to a call to FloatToStrF with an implied precision of 19 digits.


AnsiString::operator =

AnsiString

Description

Assigns the string rhs to this AnsiString.

AnsiString& __fastcall operator =(const AnsiString& rhs);


AnsiString::operator +=

AnsiString

Description

Concatenates this AnsiString and rhs, and assigns the result to this AnsiString.

AnsiString& __fastcall operator +=(const AnsiString& rhs);

The operator +=() is not supported on a property with getter/setter functions.


AnsiString::operator ==

AnsiString

Description

Compares the AnsiString with a specified string, returning true if they are the same.

bool __fastcall operator ==(const AnsiString& rhs) const;

Returns true if this AnsiString is the same as rhs, false otherwise.


AnsiString::operator !=

AnsiString

Description

Compares two strings.

bool __fastcall operator !=(const AnsiString& rhs) const;

Returns true if the strings are not the same, false otherwise.


AnsiString::operator <
operator <

Description

Compares two strings.

bool __fastcall operator <(const AnsiString& rhs) const;

Returns true if this AnsiString is less than rhs, false otherwise. The strings are compared using the numerical value of each character, and with case sensitivity.


AnsiString::operator >

AnsiString

Description

Compares two strings.

bool __fastcall operator >(const AnsiString& rhs) const;

Returns true if this AnsiString is greater than rhs, false otherwise. The strings are compared using the numerical value of each character, and with case sensitivity.


AnsiString::operator <=

AnsiString

Description

Compares two strings.

bool __fastcall operator <=(const AnsiString& rhs) const;

Returns true if this AnsiString is less than or equal to rhs, false otherwise. The strings are compared using their numerical value of each character, and with case sensitivity.


AnsiString::operator >=

AnsiString

Description

Compares two strings.

bool __fastcall operator >=(const AnsiString& rhs) const;

Returns true if this AnsiString is greater than or equal to rhs, false otherwise. The strings are compared using the numerical value of each character, and with case sensitivity.


AnsiString::AnsiCompare

AnsiString

Description

Compares the AnsiString to another specified string (case-sensitively).

int __fastcall AnsiCompare(const AnsiString& rhs) const;

Compares this AnsiString to rhs, with case sensitivity. The compare operation is controlled by the current Windows locale and is not necessarily the same as using the AnsiString comparison operators. AnsiCompare is based on a locale-specific collating order. The return value is shown below:

Condition	Return Value

S1 > S2	> 0

S1 < S2	< 0

S1 = S2	= 0


AnsiString::AnsiCompareIC

AnsiString

Description

Compares the AnsiString to another specified string (case insensitively).

int __fastcall AnsiCompareIC(const AnsiString& rhs) const; //ignorecase

Compares this AnsiString to rhs, without case sensitivity. The compare operation is controlled by the current Windows locale. The return value is shown below:

Condition	Return Value

S1 > S2	> 0

S1 < S2	< 0

S1 = S2	= 0


AnsiString::operator []

AnsiString

Description

Returns the character at a specified index in the string.

char& __fastcall operator [](const int idx);

Returns the character in the string at index value idx. The [] operator assumes a base index of 1. For example, given the string “Hello” and an index value of 2, the character returned would be ‘e’.


AnsiString::c_str

AnsiString

Description

Returns the AnsiString converted to null-terminated character array.

char* __fastcall c_str() const;

Returns a pointer a null-terminated character array containing the same characters as the AnsiString.


AnsiString::Length

AnsiString

Description

Returns the length of the AnsiString.

int __fastcall Length() const;

Returns the number of characters in this AnsiString.


AnsiString::IsEmpty

AnsiString

Description

Returns true if the AnsiString is empty.

bool __fastcall IsEmpty() const;

Returns true if this AnsiString is empty, false otherwise.


AnsiString::Unique

AnsiString

Description

Makes the AnsiString unique.

void __fastcall Unique();

Use this function to make a string unique (refcnt == 1). Unique sets the reference count on the string for the AnsiString object to 1 so that it is the only object referencing that string.


AnsiString::Insert

AnsiString

Description

Inserts a specified string into the AnsiString.

void __fastcall Insert(const AnsiString& str, int index);

Inserts the string str into this AnsiString beginning at the position of index.


AnsiString::Delete

AnsiString

Description

Removes a specified number of characters from the string.

void __fastcall Delete(int index, int count);

Removes count characters from the string beginning with the character at index.


AnsiString::SetLength

AnsiString

Description

Truncates the string to a specified length.

void __fastcall SetLength(int newLength);

Truncates the length of the string if newLength is less than the current string length. SetLength does not increase the length of the string.


AnsiString::Pos

AnsiString

Description

Returns the index at which a specified substring begins.

int __fastcall Pos(const AnsiString& subStr) const;

Returns the index in the AnsiString at which the substring subStr begins. If the substring is not contained in the AnsiString, Pos returns 0.


AnsiString::LowerCase

AnsiString

Description

Returns a lower-case version of AnsiString.

AnsiString __fastcall LowerCase() const;

Returns a new AnsiString that contains all characters in this string, converted to lower case. The conversion uses the current Windows locale (that is, it includes 8-bit international characters.). This function does not affect the original (calling) AnsiString.


AnsiString::UpperCase

AnsiString

Description

Returns an upper-case version of this AnsiString.

AnsiString __fastcall UpperCase() const;

Returns a new AnsiString that contains all characters in this string, converted to upper case. The conversion uses the current Windows locale (that is, it includes 8-bit international characters.). This function does not affect the original (calling) AnsiString.


AnsiString::Trim

AnsiString

Description

Returns a new AnsiString without leading spaces, trailing spaces, or control characters.

AnsiString __fastcall Trim() const;

Trim returns a new AnsiString removing leading and trailing spaces and control characters. Use Trim to remove blank space before and after the first printing character.


AnsiString::TrimLeft

AnsiString

Description

Returns a new AnsiString without leading spaces or control characters.

AnsiString __fastcall TrimLeft() const;

TrimLeft returns a new AnsiString removing leading spaces and control characters. Use TrimLeft to remove blank space before the first printing character.


AnsiString::TrimRight

AnsiString

Description

Returns a new AnsiString without trailing spaces or control characters.

AnsiString __fastcall TrimRight() const;

TrimRight returns a new AnsiString removing trailing spaces and control characters. Use the TrimRight function to remove blank space after the first printing character.


AnsiString::SubString

AnsiString

Description

Returns a specified substring of the AnsiString.

AnsiString __fastcall SubString(int index, int count) const;

Returns a new AnsiString that is a substring of this AnsiString. The substring contains count characters beginning at index.


AnsiString::ToInt

AnsiString

Description

Converts a string to an integer, throwing an exception if the string is invalid.

int __fastcall ToInt() const;

Converts the given string to an integer value and returns the integer. If the string doesn't contain a valid value, an EConvertError exception is thrown.


AnsiString::ToIntDef

AnsiString

Description

Converts the string to an integer, returning a default value if the string is invalid.

int __fastcall ToIntDef(int defaultValue) const;

Converts the given string to an integer value and returns the integer. If the string doesn't contain a valid value, the value given by defaultValue is returned.


AnsiString::ToDouble

AnsiString

Description

Converts the string to a floating-point value.

double __fastcall ToDouble() const;

Converts the string to a floating-point value. The string must consist of an optional sign (+ or -), a string of digits with an optional decimal point, and an optional 'E' or 'e' followed by a signed integer. Leading and trailing blanks in the string are ignored. The DecimalSeparator global variable defines the character that must be used as a decimal point. Thousand separators and currency symbols are not allowed in the string. If the string doesn't contain a valid value, an EConvertError exception is thrown.


AnsiString::WideCharBufSize

AnsiString

Description

Returns the size of the buffer required by the WideChar function.

int __fastcall WideCharBufSize() const;

Returns an integer value indicating the size of the buffer required to call the WideChar function to convert the AnsiString to a wide-character array.


AnsiString::WideChar

AnsiString

Description

Converts the AnsiString to a wide-character array.

wchar_t* __fastcall WideChar(wchar_t* dest, int destSize) const;

Converts the AnsiString to an array of wide characters, and returns the resulting wide-character array.


AnsiString::TStringMbcsByteType

AnsiString

Description

The return type of the ByteType member function.

enum TStringMbcsByteType { mbSingleByte, mbLeadByte, mbTrailByte };

TStringMbcsByteType is the return type of the AnsiString class ByteType member function.


AnsiString::ByteType

AnsiString

Description

Indicates the kind of byte that occupies a specified position in the AnsiString.

TStringMbcsByteType __fastcall ByteType(int index) const;

ByteType indicates what kind of byte exists at the Index'th byte in the AnsiString. Western locales always return mbSingleByte. Far East multibyte locales may also return mbLeadByte, indicating the byte is the first in a multibyte character sequence, and mbTrailByte, indicating that the byte is the second in a multibyte character sequence. Parameters are assumed to be valid.


AnsiString::IsLeadByte

AnsiString

Description

Returns true if the specified byte is of type mbLeadByte.

bool __fastcall IsLeadByte(int index) const;

Returns true if the byte at index in the AnsiString is of type mbLeadByte, otherwise it returns false. mbByteType indicates whether the byte is the first in a multibyte character sequence. mbLeadByte is a type of TStringMbcsByteType and is used by the ByteType member function.


AnsiString::IsTrailByte

AnsiString

Description

Returns true if the specified byte is of type mbTrailByte.

bool __fastcall IsTrailByte(int index) const;

Returns true if the byte at index in the AnsiString is of type mbTrailByte, otherwise it returns false. mbTrailType indicates whether the byte is the second in a multibyte character sequence . mbTrailByte is a type of TStringMbcsByteType and is used by the ByteType member function.


AnsiString::IsDelimiter

AnsiString

Description

Returns true if the specified character matches any character in the delimiters string.

bool __fastcall IsDelimiter(const AnsiString& delimiters, int index) const;

Returns true if the character at byte index in the AnsiString matches any character in the delimiters string, and the character is not an MBCS lead or trail byte. Otherwise it returns false.

AnsiStrings may contain multibyte characters; delimiters must contain only single byte characters.


AnsiString::IsPathDelimiter

AnsiString

Description

Returns true if the specified character is '\'.

bool __fastcall IsPathDelimiter(int index) const;

Returns true if the character at byte at index in the AnsiString is '\', and it is not a MBCS lead or trail byte. Otherwise it returns false.

Note

See ByteType for more information about multibyte characters.


AnsiString::LastDelimiter

AnsiString

Description

Returns the index of the rightmost character that matches any character in the delimiters string.

int __fastcall LastDelimiter(const AnsiString& delimiters) const;

LastDelimiter returns the byte index in this AnsiString of the rightmost whole character that matches any character in delimiters except null (#0). The AnsiString may contain multibyte characters; delimiters must contain only single byte non-null characters.

Note

Some characters must still be represented using a leading backslash. For example:

AnsiString s = “c:\\filename.ext”;

s.LastDelimiter(“\\.:” );

returns 12.

Note

See ByteType for more information about multibyte characters.


AnsiString::AnsiPos

AnsiString

Description

Returns the index at which the specified substring begins.

int __fastcall AnsiPos(const AnsiString& subStr) const;

Returns the index in the AnsiString at which the substring subStr begins. If the substring is not contained in the AnsiString Pos returns 0. This member function is the same as Pos but supports multibyte character strings.

Note

See ByteType for more information about multibyte characters.


AnsiString::AnsiLastChar

AnsiString

Description

Returns a pointer to the last full character in the AnsiString.

char* __fastcall AnsiLastChar() const;

Returns a pointer to the last full character in the AnsiString. This function supports multibyte characters.

Note

See ByteType for more information about multibyte characters.


AnsiString example

AnsiString

/* Compile with  bcc32 famille.cpp vcl.lib ole2w32.lib */

#include <vcl/dstring.h>

#include <stdio.h>

class Famille

{

private:

AnsiString FNames[10];

AnsiString GetName(int Index);

void SetName(int, AnsiString);

public:

__property AnsiString Names[int Index] = {read=GetName, write=SetName};

Famille(){}

~Famille(){}

};

AnsiString Famille::GetName(int i)

{

return FNames[i];

}

void Famille::SetName(int i,const AnsiString s)

{

FNames[i]=s;

}

int main()

{

Famille C;

C.Names[0]="Steve";   //calls Famille::SetName()

.Names[1]="Amy";

.Names[2]="Sarah";

.Names[3]="Andrew";

for (int i = 0; i <= 3; i++)

{

//calls Famille::GetName()

puts(C.Names[i].c_str());

}

}


Currency

Methods

Header

vcl/sysdefs.h

Description

Currency is a C++ class that implements the Delphi Currency data type. Currency inherits a val data member declared as int64 that holds the currency value. The range of possible currency values is 922337203685477.5808 to 922337203685477.5807. Use Currency to hold monetary values.

Note

Use only the operators within Currency. The compiler will ignore any operators you overload yourself. Use the Currency constructors to create Currency objects from pointers to other Currency objects, ints, doubles, or AnsiString values.


Currency methods

Currency	Alphabetically

In Currency

Currency

operator --

operator - (binary)

operator - (unary)

operator !

operator !=

operator %

operator %=

operator *

operator *=

operator /

operator /=

operator +

operator ++

operator +=

operator -=

operator <

operator <<

operator <=

operator =

operator ==

operator >

operator >=

operator >>

operator AnsiString

operator double

operator int


Currency methods

Currency	By object

Currency

operator - (binary)

operator - (unary)

operator !=

operator !

operator %=

operator %

operator *=

operator *

operator /=

operator /

operator ++

operator +=

operator +

operator <<

operator <=

operator <

operator ==

operator -=

operator =

operator >=

operator >>

operator >

operator AnsiString

operator --

operator double

operator int


Currency::Currency

Currency

Description

The Currency constructor is overloaded as follows:

__fastcall Currency();

Constructs a Currency object with a currency value of 0.

__fastcall Currency(double val);

Constructs a Currency object from a double value.

__fastcall Currency(int val);

Constructs a Currency object from an integer value.

__fastcall Currency(const CurrencyBase& src);

Constructs a Currency object from a base class object.

__fastcall Currency(const Currency& src);

(Copy constructor). Creates a copy of a Currency object.

__fastcall Currency(const AnsiString& src);

Constructs a Currency object from an AnsiString.


Currency::operator =

Currency

Description

The Currency assignment operator is overloaded as follows:

Currency& __fastcall operator =(double rhs);

Assigns the value of double rhs to this Currency object.

Currency& __fastcall operator =(int rhs);

Assigns the value of integer rhs to this Currency object.

Currency& __fastcall operator =(const CurrencyBase& rhs);

Assigns the value of CurrencyBase object rhs to this Currency object.

Currency& __fastcall operator =(const Currency& rhs);

Assigns the value of Currency object rhs to this Currency object.


Currency::operator +=

Currency

Description

Increments the value of this Currency object by the value of rhs.

Currency& __fastcall operator +=(const Currency& rhs);


Currency::operator -=

Currency

Description

Decrements the value of this Currency object by the value of rhs.

Currency& __fastcall operator -=(const Currency& rhs);


Currency::operator *=

Currency

Description

Assigns this Currency object the result of its initial value multiplied by the value of Currency object rhs.

Currency& __fastcall operator *=(const Currency& rhs);


Currency::operator /=

Currency

Description

Assigns this Currency object the result of its initial value divided by the value of Currency object rhs.

Currency& __fastcall operator /=(const Currency& rhs);


Currency::operator %=

Currency

Description

Assigns this Currency object the remainder of its inital value divided by by integer rhs.

Currency& __fastcall operator %=(int rhs);


Currency::operator ++

Currency

Description

The Currency unary operator ++ is overloaded as follows:

Currency& operator ++();

Increments the value of this Currency object by one.

Currency operator ++(int);

Increments the value of this Currency object by the value of the int passed to it.


Currency::operator --

Currency

Description

The Currency unary operator -- is overloaded as follows:

Currency operator --(int);

Decrements the value of this Currency object by the value of the int passed to it.

Currency& operator --();

Decrements the value of this Currency object by one.


Currency::operator +

Currency

Description

The Currency operator + is overloaded as follows:

Currency __fastcall operator +(const Currency& rhs) const;

Returns a new Currency object with a value that is the sum of this Currency object and rhs.

Currency __fastcall operator +(int rhs) const;

Returns a new Currency object with a value that is the sum of this Currency object and int rhs.

Currency __fastcall operator +(double rhs) const;

Returns a new Currency object with a value that is the sum of this Currency object and double rhs.

friend Currency __fastcall operator +(int lhs, const Currency& rhs);

Returns a new Currency object that is the sum of int lhs and Currency object rhs.

friend Currency __fastcall operator +(double lhs, const Currency& rhs);

Returns a new Currency object that is the sum of double lhs and Currency object rhs.


Currency::operator - (binary)

Currency

Description

The Currency operator - is overloaded as follows:

Currency __fastcall operator -(const Currency& rhs) const;

Returns a Currency object with a value that is the difference between this Currency object and rhs.

Currency __fastcall operator -(int rhs) const;

Returns a Currency object with a value that is the difference between this Currency object and int rhs.

Currency __fastcall operator -(double rhs) const;

Returns a Currency object with a value that is the difference between this Currency object and double rhs.

friend Currency __fastcall operator -(int lhs, const Currency& rhs);

Returns a Currency object with a value that is the difference between int lhs and Currency object rhs.

friend Currency __fastcall operator -(double lhs, const Currency& rhs);

Returns a Currency object with a value that is the difference between double lhs and Currency object rhs.


Currency::operator *

Currency

Description

The Currency operator * is overloaded as follows:

Currency __fastcall operator *(const Currency& rhs) const;

Multiplies the value of this Currency object by the value of rhs and returns a new Currency object with the resulting value.

Currency __fastcall operator *(int rhs) const;

Multiplies the value of this Currency object by the value of integer rhs and returns a new Currency object with the resulting value.

Currency __fastcall operator *(double rhs) const;

Multiplies the value of this Currency object by the value of double rhs and returns a new Currency object with the resulting value.

friend Currency __fastcall operator *(int lhs, const Currency& rhs);

Multiples the values of intger lhs and Currency object rhs and returns a new Currency object with the resulting value.

friend Currency __fastcall operator *(double lhs, const Currency& rhs);

Multiples the values of double lhs and Currency object rhs and returns a new Currency object with the resulting value.


Currency::operator /

Currency

Description

The Currency operator / is overloaded as follows:

Currency __fastcall operator /(const Currency& rhs) const;

Divides this Currency object by the value of rhs and returns a new Currency object with the resulting value.

Currency __fastcall operator /(int rhs) const;

Divides this Currency object by the value of integer rhs and returns a new Currency object with the resulting value.

Currency __fastcall operator /(double rhs) const;

Divides this Currency object by the value of double rhs and returns a new Currency object with the resulting value.

friend Currency __fastcall operator /(int lhs, const Currency& rhs);

Divides the value of int lhs by the value of Currency object rhs and returns a new Currency object with the resulting value.

friend Currency __fastcall operator /(double lhs, const Currency& rhs);

Divides the value of double lhs by the value of Currency object rhs and returns a Currency object with the resulting value.


Currency::operator %

Currency

Description

Returns a new Currency object with the value that is the remainder of this Currency object divided by integer rhs.

Currency __fastcall operator %(int rhs) const;


Currency::operator - (unary)

Currency

Description

Returns a new Currency object that is the negative value of this Currency object.

Currency __fastcall operator -() const;


Currency::operator !

Currency

Description

Returns a new Currency object that is the logical negation of this Currency object.

Currency __fastcall operator !() const;


Currency::operator ==

Currency

Description

The Currency operator == to test for equality is overloaded as follows:

bool __fastcall operator ==(const Currency& rhs) const;

Compares two Currency objects. Returns true if they have the same value, false otherwise.

bool __fastcall operator ==(int rhs) const;

Compares this Currency object with integer rhs. Returns true if they have the same value, false otherwise.

bool __fastcall operator ==(double rhs) const;

Compares this Currency object with double rhs. Returns true if they have the same value, false otherwise.


Currency::operator !=

Currency

Description

The Currency operator != to test for inequality is overloaded as follows:

bool __fastcall operator !=(const Currency& rhs) const;

Compares two Currency objects. Returns true if they do not have the same value, false otherwise.

bool __fastcall operator !=(int rhs) const;

Compares this Currency object with integer rhs. Returns true if they do not have the same value, false otherwise.

bool __fastcall operator !=(double rhs) const;

Compares this Currency object with double rhs. Returns true if they do not have the same value, false otherwise.


Currency::operator >

Currency

Description

The Currency comparison operator > is overloaded as follows:.

bool __fastcall operator >(const Currency& rhs) const;

Compares two Currency objects. Returns true if this Currency object has a greater value than rhs, false otherwise.

bool __fastcall operator >(int rhs) const;

Compares this Currency object with int rhs. Returns true if this Currency object has the greater value, false otherwise.

bool __fastcall operator >(double rhs) const;

Compares this Currency object with double rhs. Returns true if this Currency object has the greater value, false otherwise.


Currency::operator <

Currency

Description

The Currency comparison operator < is overloaded as follows:

bool __fastcall operator <(const Currency& rhs) const;

Compares two Currency objects. Returns true if this Currency object has a value less than that of rhs, false otherwise.

bool __fastcall operator <(int rhs) const;

Compares this Currency object with int rhs. Returns true if this Currency object has the lesser value, false otherwise.

bool __fastcall operator <(double rhs) const;

Compares this Currency object with double rhs. Returns true if this Currency object has the lesser value, false otherwise.


Currency::operator >=

Currency

Description

The Currency comparison operator >= is overloaded as follows:

bool __fastcall operator >=(const Currency& rhs) const;

Compares two Currency objects. Returns true if this Currency object has a greater or equal value to that of rhs, false otherwise.

bool __fastcall operator >=(int rhs) const;

Compares this Currency object with int rhs. Returns true if this Currency object has a greater or equal value, false otherwise.

bool __fastcall operator >=(double rhs) const;

Compares this Currency object with double rhs. Returns true if this Currency object has a greater or equal value, false otherwise.


Currency::operator <=

Currency

Description

The Currency comparison operator <= is overloaded as follows:

bool __fastcall operator <=(const Currency& rhs) const;

Compares two Currency objects. Returns true if this Currency object has a value less than or equal to that of rhs, false otherwise.

bool __fastcall operator <=(int rhs) const;

Compares this Currency object with int rhs. Returns true if this Currency object has a value less than or equal to that of rhs, false otherwise.

bool __fastcall operator <=(double rhs) const;

Compares this Currency object with double rhs. Returns true if this Currency object has a value less than or equal to that of rhs, false otherwise.


Currency::operator double

Currency

Description

Double is a conversion operator.

__fastcall operator double() const;

Creates a double from the Currency object.


Currency::operator int

Currency

Description

Int is a conversion operator.

__fastcall operator int() const;

Creates an int from the Currency object.


Currency::operator AnsiString

Currency	See also

Description

AnsiString is a conversion operator.

__fastcall operator AnsiString() const;

Creates a new AnsiString object from this Currency object by converting the currency value into its string representation. The conversion using the ffGeneral floating point conversion rules. For further details, see the description of the CurrToStrF and FloatToStrF methods of the AnsiString class.


Currency::operator <<

Currency	See also

Description

Writes out the Currency object, arg, to the stream, os.

inline ostream& operator <<(ostream& os, Currency& arg);

operator << writes out the Currency object as an AnsiString. For more information about the conversion and format, see operator AnsiString.


Currency::operator >>

Currency	See also

Description

Reads in the Currency object, arg, from the stream, is.

inline istream& operator >>(istream& is, Currency& arg)

operator >> reads in the Currency object as an AnsiString. For more information about the conversion and format, see operator AnsiString.


Currency example

Currency


TDateTime

Methods	See also

Header

vcl/sysdefs.h

Description

TDateTime is a C++ class that implements the Delphi TDateTime data type and the Delphi date-and-time runtime library routines that use the TDateTime data type.

The TDateTime class inherits a val data member declared as a double that holds the date-time value. The integral part of a TDateTime value is the number of days that have passed since 12/30/1899. The fractional part of a TDateTime value is the time of day.

Following are some examples of TDateTime values and their corresponding dates and times:

•	0	 12/30/1899 12:00 am

•	2.75	 1/1/1900 6:00 pm

•	-1.25	   12/29/1899 6:00 am

•	35065	   1/1/1996 12:00 am

To find the fractional number of days between two dates, subtract the two values. To increment a date and time value by a certain fractional number of days, add the fractional number to the date and time value.

Note

Use only the operators within TDateTime. The compiler will ignore any operators you overload yourself.


TDateTime methods

TDateTime	Alphabetically

In TDateTime

CurrentDate

CurrentDateTime

CurrentTime

DateString

DateTimeString

DayOfWeek

DecodeDate

DecodeTime

FileDate

FileDateToDateTime

FormatString

operator -

operator --

operator !=

operator +

operator ++

operator +=

operator -=

operator <

operator <=

operator =

operator ==

operator >

operator >=

operator AnsiString

operator double

operator int

TDateTime

TimeString


TDateTime methods

TDateTime	By object

CurrentDate

CurrentDateTime

CurrentTime

DateString

DateTimeString

DayOfWeek

DecodeDate

DecodeTime

FileDate

FileDateToDateTime

FormatString

operator !=

operator ++

operator +=

operator +

operator <=

operator <

operator ==

operator -=

operator =

operator >=

operator >

operator AnsiString

operator double

operator int

operator --

operator -

TDateTime

TimeString


TDateTime::TDateTime

TDateTime

Description

The TDateTime constructor is overloaded as follows:

__fastcall TDateTime()

Creates a TDateTime object with a val data member of zero. This date and time corresponds to 12/30/1899 12:00 am.

__fastcall TDateTime(const TDateTimeBase& src)

Creates a TDateTime object from a base class object.

__fastcall TDateTime(const TDateTime& src)

(Copy constructor) Creates a copy of a TDateTime object.

__fastcall TDateTime(const double src)

Creates a TDateTime object from a double.

__fastcall TDateTime(const int src)

Creates a TDateTime object from an int.

enum TDateTimeFlag {Date, Time, DateTime};

__fastcall TDateTime(const AnsiString& src, TDateTimeFlag flag = DateTime);

Creates a TDateTime object from an AnsiString. The flag parameter indicates whether the string contains a date, a time, or both. The default for the flag is DateTime.

__fastcall TDateTime(unsigned short year, unsigned short month, unsigned short day);

Creates a TDateTime object for a given year, month, and day specified by the corresponding parameters.

The year must be between 1 and 9999. Valid month values are 1 through 12. Valid day values are 1 through 28, 29, 30, or 31, depending on the month value. For example, the possible day values for month 2 (February) are 1 through 28 or 1 through 29, depending on whether or not the year value specifies a leap year.

If the specified values are not within range, an EConvertError exception is thrown. The resulting value is one plus the number of days between 12/30/1899 and the given date.

__fastcall TDateTime(unsigned short hour, unsigned short min, unsigned short sec, unsigned short msec);

Returns a TDateTime object for a specified hour, minute, second, and millisecond. The hour must be between 0 and 23, the minute must be between 0 and 59, the second must be between 0 and 59, and the millisecond must be between 0 and 999. If the specified values are not within range, an EConvertError exception is thrown. The resulting value is a number between 0 (inclusive) and 1 (not inclusive) that indicates the fractional part of a day given by the specified time. The value 0 corresponds to midnight, 0.5 corresponds to noon, 0.75 corresponds to 6:00 pm, etc.


TDateTime::operator =

TDateTime

Description

The TDateTime assignment operator is overloaded as follows.

TDateTime& __fastcall operator =(const TDateTimeBase& rhs);

Assigns to this TDateTime object the value of the base class object specified by rhs.

TDateTime& __fastcall operator =(const TDateTime& rhs);

Assigns to this TDateTime object the value of the TDateTime object specified by rhs.

TDateTime& __fastcall operator =(const double rhs);

Assigns to this TDateTime object the value of the double specified by rhs.

TDateTime& __fastcall operator =(const int rhs);

Assigns to this TDateTime object the value of the int specified by rhs.


TDateTime::operator +=

TDateTime

Description

The TDateTime += operator is overloaded as follows:

TDateTime& __fastcall operator +=(const TDateTimeBase& rhs);

Adds the TDateTimeBase object rhs to this TDateTime object.

TDateTime& __fastcall operator +=(const TDateTime& rhs);

Adds the TDateTime object rhs to this TDateTime object.

TDateTime& __fastcall operator +=(const double rhs);

Adds the double rhs to this TDateTime object.

TDateTime& __fastcall operator +=(const int rhs);

Adds the int rhs to this TDateTime object.


TDateTime::operator -=

TDateTime

Description

The -= operator is overloaded as follows:

TDateTime& __fastcall operator -=(const TDateTimeBase& rhs);

Subtracts the TDateTimeBase object rhs from this TDateTime object.

TDateTime& __fastcall operator -=(const TDateTime& rhs);

Subtracts the TDateTime object rhs from this TDateTime object.

TDateTime& __fastcall operator -=(const double rhs);

Subtracts the double rhs from this TDateTime object.

TDateTime& __fastcall operator -=(const int rhs);

Subtracts the int rhs from this TDateTime object.


TDateTime::operator ++

TDateTime

Description

The TDateTime unary operator++ is overloaded as follows:

TDateTime& operator ++();

Increments the date of this TDateTime object by one day. (Adds one to the val data member).

TDateTime operator ++(int);

Increments the date of this TDateTime object by the number of days specified by the int parameter.


TDateTime::operator --

TDateTime

Description

The TDateTime unary operator-- is overloaded as follows:

TDateTime& operator --();

Decrements the date of this TDateTime object by one day. (Subtracts one from the val data member).

TDateTime operator --(int);

Decrements the date of this TDateTime object by the number of days specified by the int parameter.


TDateTime::operator +

TDateTime

Description

The TDateTime operator+ is overloaded as follows:

TDateTime __fastcall operator +(const TDateTimeBase& rhs) const;

Returns the sum of this TDateTime object and rhs.

TDateTime __fastcall operator +(const TDateTime& rhs) const;

Returns the sum of two TDateTime objects.

TDateTime __fastcall operator +(const double rhs) const;

Returns the sum of this TDateTime object and the double rhs.

TDateTime __fastcall operator +(const int rhs) const;

Returns the sum of this TDateTime object and the int rhs.


TDateTime::operator -

TDateTime

Description

The TDateTime operator- is overloaded as follows:

TDateTime __fastcall operator -(const TDateTimeBase& rhs) const;

Returns the difference of this TDateTime object and rhs.

TDateTime __fastcall operator -(const TDateTime& rhs) const;

Returns the difference of two TDateTime objects.

TDateTime __fastcall operator -(const double rhs) const;

Returns the difference of this TDateTime object and the double rhs.

TDateTime __fastcall operator -(const int rhs) const;

Returns the difference of this TDateTime object and the int rhs.


TDateTime::operator ==

TDateTime

Description

Compares two TDateTime objects for equality.

bool __fastcall operator ==(const TDateTime& rhs) const;

Returns true if the two objects have the same value, false otherwise.


TDateTime::operator !=

TDateTime

Description

Compares two TDateTime objects for inequality.

bool __fastcall operator !=(const TDateTime& rhs) const;

Returns true if the two objects do not have the same value, false otherwise.


TDateTime::operator >

TDateTime

Description

Compares two TDateTime objects.

bool __fastcall operator >(const TDateTime& rhs) const;

Returns true if this TDateTime object has a value (val data member) greater than that of the object specified by rhs, and false otherwise.


TDateTime::operator <

TDateTime

Description

Compares two TDateTime objects.

bool __fastcall operator <(const TDateTime& rhs) const;

Returns true if  this TDateTime object has a value (val data member) less than that of the object specified by rhs, and false otherwise.


TDateTime::operator >=

TDateTime

Description

Compares two TDateTime objects.

bool __fastcall operator >=(const TDateTime& rhs) const;

Returns true if this TDateTime object has a value (val data member) greater than or equal to that of the object specified by rhs, and false otherwise.


TDateTime::operator <=

TDateTime

Description

Compares two TDateTime objects.

bool __fastcall coperator <=(const TDateTime& rhs) const;

Returns true if  this TDateTime object has a value (val data member) less than or equal to that of the object specified by rhs, and false otherwise.


TDateTime::operator AnsiString

TDateTime	See also

Description

AnsiString is a conversion operator.

__fastcall operator AnsiString() const;

Returns an AnsiString object that is the string conversion of this TDateTime object. The conversion uses the format specified by the LongTimeFormat global variable of the TDateTime formatting variables. Change the format of the string display by changing the values of some of the date and time variables.


TDateTime::operator double

TDateTime	See also

Description

Double is a conversion operator.

__fastcall operator double() const;

Returns a double that is the double conversion of  this TDateTime object.


TDateTime::operator int

TDateTime	See also

Description

Int is a conversion operator.

__fastcall operator int() const;

Returns an int that is the integer conversion of  this TDateTime object.


TDateTime::CurrentDate

TDateTime

Description

Returns the current date as a TDateTime value.

static TDateTime __fastcall CurrentDate();

Retrieves the current date and returns it as a new TDateTime object.


TDateTime::CurrentTime

TDateTime

Description

Returns the current time as a TDateTime value.

static TDateTime __fastcall CurrentTime();

Retrieves the current time and returns it as a new TDateTime object.


TDateTime::CurrentDateTime

TDateTime

Description

Returns the current date and time as a TDateTime value.

static TDateTime __fastcall CurrentDateTime();

Retrieves the current date and time, and returns it as a new TDateTime object.


TDateTime::DayOfWeek

TDateTime

Description

Returns the day of the week of the TDateTime

int __fastcall DayOfWeek() const;

The TDateTime object is a value that is an integer between 1 and 7. Sunday is the first day of the week and Saturday is the seventh.


TDateTime::DateString

TDateTime	See also

Description

Converts the date of the TDateTime value to a string.

AnsiString __fastcall DateString() const;

Returns the value of the TDateTime object as an AnsiString. The conversion uses the format specified by the ShortDateFormat variable.


TDateTime::DateTimeString

TDateTime	See also

Description

Converts the TDateTime value to a string.

AnsiString __fastcall DateTimeString() const;

Returns an AnsiString object containing the date and time value (the val data member) of the TDateTime object to a string. If the TDateTime value does not contain a date value, the date displays as 00/00/00. If the TDateTime value does not contain a time value, the time displays as 00:00:00 AM. You can change how the string is formatted by changing the value of one or more of the date and time formatting variables.


TDateTime::DecodeDate

TDateTime

Description

Separates the TDateTime value into year, month, and day values and stores these values in the year, month, and day parameters, respectively.

void __fastcall DecodeDate(unsigned short* year, unsigned short* month, unsigned short* day) const;

Use DecodeDate() when you need to access the year, month, or day of a TDateTime object.


TDateTime::DecodeTime

TDateTime

Description

Separates the TDateTime value into hour, minute, second, and millisecond values and stores these values in the hour, min, sec, and msec parameters, respectively.

void __fastcall DecodeTime(unsigned short* hour, unsigned short* min, unsigned short* sec, unsigned short* msec) const;

Use DecodeDate() when you need to access the hour, minute, second, or millisecond values of a TDateTime value.


TDateTime::FileDateToDateTime

TDateTime

Description

Converts a DOS file date-and-time value, specified with the fileDate argument, to a TDateTime value.

Syntax

static TDateTime __fastcall FileDateToDateTime(int fileDate);


TDateTime::FormatString

TDateTime

Description

Formats the TDateTime object using the format given by format.

AnsiString __fastcall FormatString(const AnsiString& format);

The following format specifiers are supported:

Specifier	Displays

c	Displays the date using the format given by the ShortDateFormat global variable, followed by the time using the format given by the LongTimeFormat global variable. The time is not displayed if the fractional part of the DateTime value is zero.

d	Displays the day as a number without a leading zero (1-31).

dd	Displays the day as a number with a leading zero (01-31).

ddd	Displays the day as an abbreviation (Sun-Sat) using the strings given by the ShortDayNames global variable.

dddd	Displays the day as a full name (Sunday-Saturday) using the strings given by the LongDayNames global variable.

ddddd	Displays the date using the format given by the ShortDateFormat global variable.

dddddd	Displays the date using the format given by the LongDateFormat global variable.

m	Displays the month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mm	Displays the month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mmm	Displays the month as an abbreviation (Jan-Dec) using the strings given by the ShortMonthNames global variable.

mmmm	Displays the month as a full name (January-December) using the strings given by the LongMonthNames global variable.

yy	Displays the year as a two-digit number (00-99).

yyyy	Displays the year as a four-digit number (0000-9999).

h	Displays the hour without a leading zero (0-23).

hh	Displays the hour with a leading zero (00-23).

n	Displays the minute without a leading zero (0-59).

nn	Displays the minute with a leading zero (00-59).

s	Displays the second without a leading zero (0-59).

ss	Displays the second with a leading zero (00-59).

t	Displays the time using the format given by the ShortTimeFormat global variable.

tt	Displays the time using the format given by the LongTimeFormat global variable.

am/pm	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon, and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

a/p	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

ampm	Uses the 12-hour clock for the preceding h or hh specifier, and displays the contents of the TimeAMString global variable for any hour before noon, and the contents of the TimePMString global variable for any hour after noon.

/	Displays the date separator character given by the DateSeparator global variable.

:	Displays the time separator character given by the TimeSeparator global variable.

'xx'/"xx"	Characters enclosed in single or double quotes are displayed as is, and do not affect formatting.

If the string given by the format parameter is empty, the TDateTime value is formatted as if a c format specifier had been given.


TDateTime::FileDate

TDateTime

Converts the date-and-time value to a DOS date-and-time stamp.

int __fastcall FileDate() const;


TDateTime::TimeString

TDateTime	See also

Description

Converts the TDateTime object to an AnsiString.

AnsiString __fastcall TimeString() const;

Returns an AnsiString object containing the time value (the fraction of the val data member) of the TDateTime object to a string. The conversion uses the format specified by the LongTimeFormat variable. Change the format of how the string is displayed by changing the value of one or more of the date-and time formatting variables.


Set

Methods	Example

Header

vcl/sysdefs.h

Description

The Set<type, minval, maxval> is a C++ class template that implements the Delphi intrinsic type set.

Syntax

template<class T, unsigned char minEl, unsigned char maxEl>

class __declspec(delphireturn) Set;

You must specify three template parameters:

Parameter	Usage

type	the type of the elements (usually int, char, or an enum type)

minval	the minimum value the set can hold (this value cannot be less then 0)

maxval	the maximum value the set can hold (this value cannot be greater than 255)

Each instantiation of a Set creates an object based on all three parameters. Therefore, the following are two distinct types because they have different mininum and maximum values:

Set <char, ‘A’, ‘C’> s1;

Set <char, ‘X’, ‘Z’> s2;

if (s1 == s2)   // ERROR; illegal struct.

To create multiple instances of a Set type, use a typedef expression.

typedef Set <char, ‘A’,‘Z’> UPPERCASESet;

The declaration of a Set variable does not initialize the variable. You can declare the set types and initialize them by using this syntax.

UPPERCASESet s1;

s1 << ‘A’ << ‘B’ << ‘C’;   // Initialize

UPPERCASESet s2;

s2 << ‘X’ << ‘Y’ << ‘Z’;   // Initialize


Set methods

Set	Alphabetically

In Set

Clear

Contains

operator -

operator !=

operator *

operator *=

operator +=

operator << (addition)

operator << (streaming)

operator -=

operator +

operator =

operator ==

operator >> (streaming)

operator >> (subtraction)

Set


Set methods

Set	By object

Clear

Contains

operator !=

operator *=

operator *

operator +=

operator +

operator << (addition)

operator << (streaming)

operator ==

operator -=

operator =

operator >> (streaming)

operator >> (subtraction)

operator -

Set


Set::Set

Set

Description

Set has two constructors.

__fastcall Set();

Creates an empty Set object.

__fastcall Set(const Set& src);

(Copy constructor) Creates a copy of a Set object.


Set::Clear

Set

Removes all elements from the Set object.

Set& __fastcall Clear();


Set::Contains

Set

Description

Queries whether the Set contains a specific element.

bool __fastcall Contains(const T el) const;

Returns true if the Set object contains the element el that is of type T, false otherwise.


Set::operator =

Set

Set& __fastcall operator =(const Set& rhs);

Assigns the contents of rhs to the Set object.


Set::operator +=

Set

Description

Assigns the Set object the union of its own data and that of the Set object specified by rhs.

Set& __fastcall operator +=(const Set& rhs);

Performs an or operation on the data from both Set objects.


Set::operator -=

Set

Description

Assigns the Set object the difference between its own data and that of the Set object specified by rhs.

Set& __fastcall operator -=(const Set& rhs);

Performs an xor operation on the data from both Set objects.


Set::operator *=

Set

Description

Assigns the Set object the intersection of its own data and that of the Set object specified by rhs.

Set& __fastcall operator *=(const Set& rhs);

Performs an and operation on the data from both Set objects.


Set::operator +

Set

Description

Returns a new Set object that is the union of two Set objects.

Set __fastcall operator +(const Set& rhs) const;

Performs an or operation on the data from both Set objects.


Set::operator -

Set

Description

Returns a new Set object that is the difference between two Sets.

Set __fastcall operator -(const Set& rhs) const;

Performs an xor operation on the data from both Set objects.


Set::operator *

Set

Description

Returns a new Set object that is the intersection of two Sets.

Set __fastcall operator *(const Set& rhs) const;

Performs an and operation on the data from both Set objects.


Set::operator << (addition)

Set

Set& __fastcall operator <<(const T el);

Description

Adds element el, of type T, to the Set object.


Set::operator << (streaming)

Set

operator << streams out a specified Set.

friend ostream& operator <<(ostream& os, const Set& arg);

Description

Streams text output for a specified Set object, writing ‘1’s and ‘0’s that indicate whether each element is contained in the Set. For example, operator >> is useful for Sets of options associated with a particular Windowed control style. operator << returns the resulting stream.


Set::operator >> (subtraction)

Set

Description

Removes element el, of type T, from the Set object.

Set& __fastcall operator >>(const T el);


Set::operator >> (streaming)

Set

operator >> streams in a specified Set.

friend istream& operator >>(istream& is, Set& arg);

Description

Streams text input for a specified Set object, reading in ‘1’s and ‘0’s that indicate whether each element is contained in the Set. For example, operator >> is useful for Sets of options associated with a particular Windowed control style. operator >> returns the resulting stream.


Set::operator ==

Set

Description

Compares two Set objects.

bool __fastcall operator ==(const Set& rhs) const;

Returns true if the two Set objects contain the same elements, false otherwise.


Set::operator !=

Set

Description

Compares two Set objects.

bool __fastcall operator !=(const Set& rhs) const ;

Returns true if the two Set objects do not contain the same elements, false otherwise.


Set example

Set

#include <sysdefs.h>

#include <iostream.h>

typedef Set<char,'U','Z'> UpperSet;

typedef Set<char,'a','z'> LowerSet;

typedef Set<char,'a','j'> HalfLowerSet;

void set_example()

{

LowerSet ae, ae2, ac, de;

UpperSet AE, AE2, AC, DE;

HalfLowerSet aj;

// Both of these are false. Sets are empty until members are added.

cout <<"Set ae " << (ae.Contains('a')?"does":"does not") << " contain 'a' " << endl;

cout <<"Set AE " << (AE.Contains('C')?"does":"does not") << " contain 'C' " << endl;

ae  << 'a' << 'b' << 'c' << 'd' << 'e';

ae2 << 'a' << 'b' << 'c' << 'd' << 'e';

ac  << 'a' << 'b' << 'c';

de  << 'd' << 'e';

aj  << 'd' << 'e';

DE  << 'D' << 'E';

cout <<"Now, set ae " << (ae.Contains('a')?"does":"does not") << " contain 'a' " << endl;

/***

 Compile-time error! Although sets 'de' and 'aj' contain the same members, they are different types of sets and cannot be compared.

****/

//cout << (de==aj?" == ":" != ") << endl;

// Sets support operations * (intersection),+ (union) and - (difference).

cout << "Set ae " << (ae==(ac+de)?" == ":" != ") << "set ac + de." << endl;

cout << "Set de " << (de==(ae-ac)?" == ":" != ") << "set ae - ac." << endl;

// Clear member function

cout << "Set ae2: " << ae2 << endl;

ae2.Clear();

cout << "Set ae2: " << ae2 << " after ae2.Clear()" << endl;

// Sets also support operations *= (intersection),+= (union) and -= (difference).

ae2+=ac;

cout << "Union ae2+=ac: Set ae2 " << (ae2==ac?" == ":" != ") << "set ac." << endl;

ae2+=de;

cout << "Union ae2+=de: Set ae2 " << (ae2==ae?" == ":" != ") << "set ae." << endl;

ae2-=ac;

cout << "Difference ae2-=ac: Set ae2 " << (ae2==de?" == ":" != ") << "set de." << endl;

}

int main()

{

set_example();

return 0;

}


TVarData

Header

vcl/sysdefs.h

Description

TVarData is the base class for Variant. The internal structure of a Variant as designated by TVarData is identical to the Variant type used by OLE and the Win32 APIs.

Syntax

class TVarData {

  public:

    Word VType;

    Word Reserved1;

    Word Reserved2;

    Word Reserved3;

    union {

      Smallint VSmallint;

      Integer VInteger;

      Single VSingle;

      Double VDouble;

      CurrencyBase VCurrency;

      TDateTimeBase VDate;

      PWideChar VOleStr;

      Ole2::IDispatch* VDispatch;

      Integer VError;

      WordBool VBoolean;

      Ole2::IUnknown* VUnknown;

      Byte VByte;

      Pointer VString;

      PVarArray VArray;

      Pointer VPointer;

    };

};

The VType of TVarData contains the type code of the variant in the lower twelve bits (the bits defined by varTypeMask).

The following values are used for VType:

#define varEmpty (Byte)(0)

#define varNull (Byte)(1)

#define varSmallint (Byte)(2)

#define varInteger (Byte)(3)

#define varSingle (Byte)(4)

#define varDouble (Byte)(5)

#define varCurrency (Byte)(6)

#define varDate (Byte)(7)

#define varOleStr (Byte)(8)

#define varDispatch (Byte)(9)

#define varError (Byte)(10)

#define varBoolean (Byte)(11)

#define varVariant (Byte)(12)

#define varUnknown (Byte)(13)

#define varByte (Byte)(17)

#define varString (Word)(256)

#define varTypeMask (Word)(4095)

#define varArray (Word)(8192)

#define varByRef (Word)(16384)

#define varStrArg (Byte)(72)

#define vtInteger (Byte)(0)

#define vtBoolean (Byte)(1)

#define vtChar (Byte)(2)

#define vtExtended (Byte)(3)

#define vtString (Byte)(4)

#define vtPointer (Byte)(5)

#define vtPChar (Byte)(6)

#define vtObject (Byte)(7)

#define vtClass (Byte)(8)

#define vtWideChar (Byte)(9)

#define vtPWideChar (Byte)(10)

#define vtAnsiString (Byte)(11)

#define vtCurrency (Byte)(12)

#define vtVariant (Byte)(13)

In addition, the varArray bit may be set to indicate that the variant is an array, and the varByRef bit may be set to indicate that the variant contains a reference as opposed to a value.

Word Reserved1;

    Word Reserved2;

    Word Reserved3;

The Reserved1, Reserved2, and Reserved3 members of TVarData are unused.

union { Smallint VSmallint;

      Integer VInteger;

      Single VSingle;

      Double VDouble;

      CurrencyBase VCurrency;

      TDateTimeBase VDate;

      PWideChar VOleStr;

      Ole2::IDispatch* VDispatch;

      Integer VError;

      WordBool VBoolean;

      Ole2::IUnknown* VUnknown;

      Byte VByte;

      Pointer VString;

      PVarArray VArray;

      Pointer VPointer;

    };

};

The contents of the remaining eight bytes of TVarData depend on the VType field. If neither the varArray nor the varByRef bits are set, the variant contains a value of the given type.

If the varArray bit is set, the variant contains a pointer to a TVarArray structure that defines the specifics of the array. The type of each array element is given by the varTypeMask bits in VType.

If the varByRef bit is set, the variant contains a reference to a value of the type given by the varTypeMask and varArray bits in VType.


Variant

Methods	Example

The Variant class is a C++Builder implementation of the Delphi intrinsic type Variant.

Header

vcl/sysdefs.h

Description

In C++Builder, the syntax for using the Variant type is different from the Delphi usage. For example, if you have the following Delphi code.

V: Variant;

V := VarArrayCreate([0,HighVal,0,HighVal],varInteger);

In C++Builder, you can use Variant and OPENARRAY like this.

Variant V(OPENARRAY(int,(0,HighVal,0,HighVal)),varInteger);

The Variant type is capable of representing values that change type dynamically. Whereas a variable of any other type is statically bound to that type, a variable of the Variant type can assume values of differing types at run-time. The Variant type is most commonly used in situations where the actual type to be operated upon varies or is unknown at compile-time.

A Variant has the following characteristics:

•	Variants can contain integer values, real values, string values, boolean values, date-and-time values, and OLE Automation objects. In addition, variants can contain arrays of varying size and dimension with elements of any of these types.

•	The special Variant value Unassigned is used to indicate that a variant has not yet been assigned a value, and the special variant value Null is used to indicate unknown or missing data.

•	A Variant can be combined with other variants and it can be constructed from any of the following data types. The compiler automatically performs the necessary type conversions.

•	short

•	int

•	float

•	double

•	Currency

•	TDateTime

•	bool

•	WordBool

•	Byte

•	AnsiString&

•	char *

•	wchar_t * const

•	Ole2::IDispatch* const

•	Ole2::IUnknown* const

When a Variant contains an OLE Automation object, the variant can be used to get and set properties of the object, and to invoke methods on the object.

Variant variables are always initialized to be Unassigned when they are first created. This is true whether a variant variable is global, local, or part of a structure such as an array.

Note that while variants offer great flexibility, they also consume more memory than regular variables, and operations on variants are substantially slower than operations on statically typed values.

Note

Use only the operators declared within Variant. The compiler will ignore any operators you overload yourself.

Note

For binary operators, if one operand is of type Variant, the other operand is automatically converted to type Variant.


Variant methods

Variant	Alphabetically

In Variant

~Variant

ArrayDimCount

ArrayHighBound

ArrayLock

ArrayLowBound

ArrayRedim

ArrayUnlock

AsType

ChangeType

Clear

CreateObject

Exec

GetActiveObject

GetElement

GetError

IsArray

IsEmpty

IsNull

OleFunction

OleProcedure

OlePropertyGet

OlePropertySet

operator - (binary)

operator - (unary)

operator !

operator !=

operator %

operator %=

operator &

operator &=

operator *

operator *=

operator /

operator /=

operator ^

operator ^=

operator |

operator |=

operator +

operator +=

operator <

operator << (left shift)

operator << (streaming)

operator <<=

operator <=

operator -=

operator =

operator ==

operator >

operator >=

operator >> (right shift)

operator >>=

operator AnsiString

operator bool

operator Byte

operator Currency

operator double

operator float

operator int

operator Ole2::IDispatch

operator Ole2::IUnknown

operator short

operator TDateTime

operator wchar_t

operator WordBool

PutElement

SetError

Type

Variant (by reference)

Variant (by value)

Variant (for arrays)


Variant methods

Variant	By object

~Variant

ArrayDimCount

ArrayHighBound

ArrayLock

ArrayLowBound

ArrayRedim

ArrayUnlock

AsType

ChangeType

Clear

CreateObject

Exec

GetActiveObject

GetElement

GetError

IsArray

IsEmpty

IsNull

OleFunction

OleProcedure

OlePropertyGet

OlePropertySet

operator - (binary)

operator - (unary)

operator !=

operator !

operator %=

operator %

operator &=

operator &

operator *=

operator *

operator /=

operator /

operator ^=

operator ^

operator |=

operator |

operator +=

operator +

operator << (left shift)

operator << (streaming)

operator <<=

operator <=

operator <

operator ==

operator -=

operator =

operator >=

operator >> (right shift)

operator >>=

operator >

operator AnsiString

operator bool

operator Byte

operator Currency

operator double

operator float

operator int

operator Ole2::IDispatch

operator Ole2::IUnknown

operator short

operator TDateTime

operator wchar_t

operator WordBool

PutElement

SetError

Type

Variant (by reference)

Variant (by value)

Variant (for arrays)


Variant::Variant (by value)

Variant

Description

The Variant constructor is overloaded as follows:

__fastcall Variant();

Creates a Variant object of type Unassigned.

__fastcall Variant(const Variant& src);

Creates a copy of a Variant object. (Copy constructor).

__fastcall Variant(const short src);

Creates a Variant object from a short.

__fastcall Variant(const int src);

Creates a Variant object from an int.

__fastcall Variant(const float src);

Creates a Variant object from a float.

__fastcall Variant(const double src);

Creates a Variant object from a double.

__fastcall Variant(const Currency src);

Creates a Variant object from a Currency object.

__fastcall Variant(const TDateTime src);

Creates a Variant object from a TDateTime object.

__fastcall Variant(const bool src);

Creates a Variant object from a bool.

__fastcall Variant(const WordBool src);

Creates a Variant object from a WordBool.

__fastcall Variant(const Byte src);

Creates a Variant object from a Byte.

__fastcall Variant(const AnsiString& src);

Creates a Variant object from an AnsiString.

__fastcall Variant(const char* src);

Creates a Variant object from a character array.

__fastcall Variant(wchar_t* const src);

Creates a Variant object from a wide character array.

__fastcall Variant(Ole2::IDispatch* const src);

Creates a Variant object from an OLE Automation object containing the IDispatch interface pointer specified by src.

__fastcall Variant(Ole2::IUnknown* const src);

Creates a Variant object from an OLE object containing the IUnknown interface pointer specified by src.


Variant::Variant (by reference)

Variant

Description

The following constructors set the varByRef bit meaning that the variant contains a reference as opposed to a value. varByRef is one of the possible values for the VType public data member of the base class TVarData.

__fastcall Variant(short* src);

Creates a Variant object from the reference to the short specified by src.

__fastcall Variant(int* src);

Creates a Variant object from the reference to the int specified by src.

__fastcall Variant(float* src);

Creates a Variant object from the reference to the float specified by src.

__fastcall Variant(double* src);

Creates a Variant object from the reference to the double specified by src.

__fastcall Variant(Currency* src);

Creates a Variant object from the reference to the Currency object specified by src.

__fastcall Variant(TDateTime* src);

Creates a Variant object from the reference to the TDateTime object specified by src.

__fastcall Variant(WordBool* src);

Creates a Variant object from the reference to the WordBool specified by src.

__fastcall Variant(Byte* src);

Creates a Variant object from the reference to the Byte specified by src.

__fastcall Variant(wchar_t** src);

Creates a Variant object from the reference to the wide character array specified by src.


Variant::Variant (for arrays)

Variant

The following constructors create Variant arrays:

__fastcall Variant(const int* bounds, const int boundsSize, Word varType);

Creates a variant array with the bounds given by bounds and the element type given by varType. The bounds parameter must contain an even number of values, and each pair of values specify the upper and lower bounds of one dimension of the array. The element type of the array, given by the varType parameter, must be one of the TVarData type codes, and cannot include the varArray or varByRef bits. The element type cannot be varString.

To create a variant array of strings, use the varOleStr type code. If the element type is varVariant, the elements of the array are themselves variants and can, in turn, contain variant arrays.

__fastcall Variant(const Variant* values, const int valuesSize);

Creates a one-dimensional Variant array with the elements given by the values parameter. The low bound of the returned array is zero, the high bound is the number of values given by the values parameter minus one, and the element type is Variant.


Variant::~Variant

Variant

Description

~Variant is the destructor for a Variant object.

__fastcall ~Variant();

~Variant destroys the object.


Variant::operator =

Variant

Description

The assignment operator copies the Variant specified by rhs into this Variant.

Variant& __fastcall operator =(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator +=

Variant

Description

Adds the Variant specified by rhs to this Variant object.

Variant& __fastcall operator +=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator -=

Variant

Description

Subtracts the Variant specified by rhs from this Variant object.

Variant& __fastcall operator -=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator *=

Variant

Description

Multiplies this Variant by the Variant specified by rhs.

Variant& __fastcall operator *=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator /=

Variant

Description

Divides this Variant by the Variant rhs.

Variant& __fastcall operator /=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator %=

Variant

Description

The mod operator returns this Variant as the modulus of its original value and the Variant specified by rhs.

Variant& __fastcall operator %=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator &=

Variant

Description

Returns this Variant after performing a bitwise and operation.

Variant& __fastcall operator &=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator |=

Variant

Description

Returns this Variant after performing a bitwise or operation.

Variant& __fastcall operator |=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator ^=
operator ^=

Description

Returns this Variant after performing a bitwise xor operation.

Variant& __fastcall operator ^=(const Variant& rhs);

The meaning of this operation is determined by the actual types of the Variants. If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator <<=

Variant

Description

Performs a bitwise shl (left shift) operation on this Variant.

Variant& __fastcall operator <<=(const Variant& rhs);

If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator >>=

Variant

Description

Performs a bitwise shr (right shift) operation on this Variant.

Variant& __fastcall operator >>=(const Variant& rhs);

If the Variants can be converted to types that make sense for the given operation, the assignment is performed. If any of these operations is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator ==

Variant

Description

For the following comparison operators if the comparison is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator == is overloaded as follows:

bool __fastcall operator ==(const Variant& rhs) const;

Compares this Variant object with the Variant specified by rhs. Returns true if they are equal, false otherwise.

bool __fastcall operator ==(int rhs) const;

Compares this Variant object with the int specified by rhs. Returns true if they are equal, false otherwise.

bool __fastcall operator ==(double rhs) const;

Compares this Variant object with the double specified by rhs. Returns true if they are equal, false otherwise.


Variant::operator !=

Variant

Description

For the following comparison operators if the comparison is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator != is overloaded as follows:

bool __fastcall operator !=(const Variant& rhs) const;

Compares this Variant object with the Variant specified by rhs. Returns true if they are equal, false otherwise.

bool __fastcall operator !=(int rhs) const;

Compares this Variant object with the int specified by rhs. Returns true if they are equal, false otherwise.

bool __fastcall operator !=(double rhs) const;

Compares this Variant object with the double specified by rhs. Returns true if they are equal, false otherwise.


Variant::operator <

Variant

Description

For the following comparison operators if the comparison is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator < is overloaded as follows:

bool __fastcall operator <(const Variant& rhs) const;

Returns true if this Variant object is less than the Variant specified by rhs, false otherwise.

bool __fastcall operator < (int rhs) const;

Returns true if this Variant object is less than the int specified by rhs, false otherwise.

bool __fastcall operator < (double rhs) const;

Returns true if this Variant object is less than the double specified by rhs, false otherwise.


Variant::operator >

Variant

Description

For the following comparison operators if the comparison is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator > is overloaded as follows:

bool __fastcall operator >(const Variant& rhs) const;

Returns true if this Variant object is greater than the Variant specified by rhs, false otherwise.

bool __fastcall operator > (int rhs) const;

Returns true if this Variant object is greater than the int specified by rhs, false otherwise.

bool __fastcall operator > (double rhs) const;

Returns true if this Variant object is greater than the double specified by rhs, false otherwise.


Variant::operator <=

Variant

Description

For the following comparison operators if the comparison is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator <= is overloaded as follows:

bool __fastcall operator <=(const Variant& rhs) const;

Returns true if this Variant object is less than or equal to the Variant specified by rhs, false otherwise.

bool __fastcall operator <=(int rhs) const;

Returns true if this Variant object is less than or equal to the int specified by rhs, false otherwise.

bool __fastcall operator <=(double rhs) const;

Returns true if this Variant object is less than or equal to the double specified by rhs, false otherwise.


Variant::operator >=

Variant

Description

For the following comparison operators if the comparison is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator >= is overloaded as follows:

bool __fastcall operator >=(const Variant& rhs) const;

Returns true if this Variant object is greater than or equal to the Variant specified by rhs, false otherwise.

bool __fastcall operator >=(int rhs) const;

Returns true if this Variant object is greater than or equal to the int specified by rhs, false otherwise.

bool __fastcall operator >=(double rhs) const;

Returns true if this Variant object is greater than or equal to the double specified by rhs, false otherwise.


Variant::operator +

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator + is overloaded as follows:

Variant __fastcall operator +(const Variant& rhs) const;

Returns a new Variant that is the sum of this Variant and rhs.

Variant __fastcall operator +(int rhs) const;

Adds this Variant to the int specified by rhs and returns a new Variant with that value.

Variant __fastcall operator +(double rhs) const;

Returns a new Variant that is the sum of this Variant and the double specified by rhs.


Variant::operator - (binary)

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator - is overloaded as follows:

Variant __fastcall operator -(const Variant& rhs) const;

Returns a new Variant that is the difference of this Variant and the Variant rhs.

Variant __fastcall operator -(const AnsiString& rhs) const;

Returns a new Variant that is the difference of this Variant and the AnsiString specified by rhs.

Variant __fastcall operator -(int rhs) const;

Returns a new Variant that is the difference of this Variant and the int specified by rhs..

Variant __fastcall operator -(double rhs) const;

Returns a new Variant that is the difference of this Variant and the double specified by rhs.


Variant::operator *

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator * is overloaded as follows:

Variant __fastcall operator *(const Variant& rhs) const;

Returns a new Variant that is the result of multiplying this Variant with Variant rhs.

Variant __fastcall operator *(const AnsiString& rhs) const;

Returns a new Variant that is the result of multiplying this Variant with AnsiString rhs.

Variant __fastcall operator *(int rhs) const;

Returns a new Variant that is the result of multiplying this Variant with int rhs.

Variant __fastcall operator *(double rhs) const;

Returns a new Variant that is the result of multiplying this Variant with double rhs.


Variant::operator /

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator / is overloaded as follows:

Variant __fastcall operator /(const Variant& rhs) const;

Returns a new Variant that is the result of dividing this Variant by Variant rhs.

Variant __fastcall operator /(const AnsiString& rhs) const;

Returns a new Variant that is the result of dividing this Variant by AnsiString rhs.

Variant __fastcall operator /(int rhs) const;

Returns a new Variant that is the result of dividing this Variant by int rhs.

Variant __fastcall operator /(double rhs) const;

Returns a new Variant that is the result of dividing this Variant by double rhs.


Variant::operator %

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator % is overloaded as follows:

Variant __fastcall operator %(const Variant& rhs) const;

Returns a new Variant the is the modulus of this Variant and Variant rhs.

Variant __fastcall operator %(const AnsiString& rhs) const;

Returns a new Variant the is the modulus of this Variant and AnsiString rhs.

Variant __fastcall operator %(int rhs) const;

Returns a new Variant the is the modulus of this Variant and int rhs.

Variant __fastcall operator %(double rhs) const;

Returns a new Variant the is the modulus of this Variant and double rhs.


Variant::operator &

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator & is overloaded as follows:

Variant __fastcall operator &(const Variant& rhs) const;

Returns a new Variant that is the result of a bitwise and operation on this Variant using Variant rhs as the rvalue.

Variant __fastcall operator &(const AnsiString& rhs) const;

Returns a new Variant that is the result of a bitwise and operation on this Variant using AnsiString rhs as the rvalue.

Variant __fastcall operator &(int rhs) const;

Returns a new Variant that is the result of a bitwise and operation on this Variant using int rhs as the rvalue.

Variant __fastcall operator &(double rhs) const;

Returns a new Variant that is the result of a bitwise and operation on this Variant using double rhs as the rvalue.


Variant::operator |

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator | is overloaded as follows:

Variant __fastcall operator |(const Variant& rhs) const;

Returns a new Variant that is the result of a bitwise or operation on this Variant using Variant rhs as the rvalue.

Variant __fastcall operator |(const AnsiString& rhs) const;

Returns a new Variant that is the result of a bitwise or operation on this Variant using AnsiString rhs as the rvalue.

Variant __fastcall operator |(int rhs) const;

Returns a new Variant that is the result of a bitwise or operation on this Variant using int rhs as the rvalue.

Variant __fastcall operator |(double rhs) const

Returns a new Variant that is the result of a bitwise or operation on this Variant using double rhs as the rvalue.


Variant::operator ^
operator ^

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator ^ is overloaded as follows:

Variant __fastcall operator ^(const Variant& rhs) const;

Returns a new Variant that is the result of a bitwise xor operation on this Variant using Variant rhs as the rvalue.

Variant __fastcall operator ^(const AnsiString& rhs) const;

Returns a new Variant that is the result of a bitwise xor operation on this Variant using AnsiString rhs as the rvalue.

Variant __fastcall operator ^(int rhs) const;

Returns a new Variant that is the result of a bitwise xor operation on this Variant using int rhs as the rvalue.

Variant __fastcall operator ^(double rhs) const;

Returns a new Variant that is the result of a bitwise xor operation on this Variant using double rhs as the rvalue.


Variant::operator << (left shift)

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator << is overloaded as follows:

Variant __fastcall operator <<(const Variant& rhs) const;

Returns a new Variant that is the result of a shl (left shift) operation on this Variant using Variant rhs as the rvalue.

Variant __fastcall operator <<(const AnsiString& rhs) const;

Returns a new Variant that is the result of a shl (left shift) operation on this Variant using AnsiString rhs as the rvalue.

Variant __fastcall operator <<(int rhs) const;

Returns a new Variant that is the result of a shl (left shift) operation on this Variant using int rhs as the rvalue.

Variant __fastcall operator <<(double rhs) const;

Returns a new Variant that is the result of a shl (left shift) operation on this Variant using double rhs as the rvalue.


Variant::operator << (streaming)

Variant

friend ostream& operator <<(ostream& os, const Variant& arg);

Writes out the Variant specified by arg to the stream specified by os.


Variant::operator >> (right shift)

Variant

Description

For the following binary operators if the operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant operator >> is overloaded as follows:

Variant __fastcall operator >>(const Variant& rhs) const;

Returns a new Variant that is the result of a shr (right shift) operation on this Variant using Variant rhs as the rvalue.

Variant __fastcall operator >>(const AnsiString& rhs) const;

Returns a new Variant that is the result of a shr (right shift) operation on this Variant using AnsiString rhs as the rvalue.

Variant __fastcall operator >>(int rhs) const;

Returns a new Variant that is the result of a shr (right shift) operation on this Variant using int rhs as the rvalue.

Variant __fastcall operator >>(double rhs) const;

Returns a new Variant that is the result of a shr (right shift) operation on this Variant using double rhs as the rvalue.


Variant::operator - (unary)

Variant

Variant __fastcall operator -() const;

Returns a new Variant that has the negative value of this Variant.


Variant::operator !

Variant

Variant __fastcall operator !() const;

Returns a new Variant that is the logical negation of this Variant.


Variant::operator short

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant short operator is overloaded as follows:

__fastcall operator short() const;

Returns a short that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator short*();

Returns a reference to a short that is a conversion of this Variant.


Variant::operator int

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant int operator is overloaded as follows:

__fastcall operator int() const;

Returns an int that is the integer conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator int*();

Returns a reference to an int that is a conversion of this Variant.


Variant::operator float

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant float operator is overloaded as follows:

__fastcall operator float() const;

Returns a float that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator float*();

Returns a reference to a float that is a conversion of this Variant.


Variant::operator double

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant double operator is overloaded as follows:

__fastcall operator double() const;

Returns a double that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator double*();

Returns a reference to a double that is a conversion of this Variant.


Variant::operator Currency

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant Currency operator is overloaded as follows:

__fastcall operator Currency() const;

Returns a Currency object that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator Currency*();

Returns a reference to a Currency object that is a conversion of this Variant.


Variant::operator TDateTime

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant TDateTime operator is overloaded as follows:

__fastcall operator TDateTime() const;

Returns a TDateTime object that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator TDateTime*();

Returns a reference to a TDateTime object that is a conversion of this Variant.


Variant::operator bool

Variant

Description

Returns a bool that is a conversion of this Variant.

__fastcall operator bool() const;

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator WordBool

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant WordBool operator is overloaded as follows:

__fastcall operator WordBool() const;

Returns a WordBool that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator WordBool*();

Returns a reference to a WordBool that is a conversion of this Variant.


Variant::operator Byte

Variant

Description

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.

The Variant Byte operator is overloaded as follows:

__fastcall operator Byte() const;

Returns a Byte that is a conversion of this Variant.

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator Byte*();

Returns a reference to a Byte that is a conversion of this Variant.


Variant::operator AnsiString

Variant

Description

Returns an AnsiString object that is a conversion of this Variant.

__fastcall operator AnsiString() const;

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator Ole2::IDispatch

Variant

Description

Returns an OLE Automation object IDispatch interface pointer that is a conversion of this Variant.

__fastcall operator Ole2::IDispatch*();

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator Ole2::IUnknown

Variant

Description

Returns an OLE object IUnknown interface pointer that is a conversion of this Variant.

__fastcall operator Ole2::IUnknown*();

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::operator wchar_t

Variant

Description

The following conversion operator converts the Variant to the specified type and sets the varByRef bit, meaning that the variant contains a reference as opposed to a value.

__fastcall operator wchar_t**();

Returns a reference to a wide character array that is a conversion of this Variant.

If the conversion operation is not possible because of an invalid variant type conversion, an EVariantError exception is thrown.


Variant::ArrayDimCount

Variant

Description

Returns the number of dimensions of the given variant.

int __fastcall ArrayDimCount() const;

The resulting value is zero if the given variant is not a Variant array.


Variant::ArrayHighBound

Variant

Description

Returns the high bound of the given dimension in the given variant array.

int __fastcall ArrayHighBound(const int dim = 1) const;

The dim parameter should be 1 for the leftmost dimension, 2 for the second leftmost dimension, and so on. An EVariantError exception is raised if the variant given by A is not an array, or if the dimension specified by dim does not exist.


Variant::ArrayLock

Variant

Description

Locks the given variant array and returns a pointer to the data stored in the array.

Pointer __fastcall ArrayLock();

While locked, a variant array can not be resized and any calls to ArrayRedim will fail. Once locked, a variant array must later be unlocked using ArrayUnlock. An EVariantError exception is raised if the variant given by A is not an array.

The pointer returned by ArrayLock points to an array of elements in which the leftmost dimension increases first. In other words, the dimensions of the returned array pointer are reversed from the dimensions of the variant array.

Once it is verified that a variant array has the correct bounds and dimensions, ArrayLock can be used to gain direct access to the array data which results in much improved performance.


Variant::ArrayLowBound

Variant

Description

Returns the low bound of the given dimension in the given variant array.

int __fastcall ArrayLowBound(const int dim = 1) const;

The dim parameter should be 1 for the leftmost dimension, 2 for the second leftmost dimension, and so on. An EVariantError exception is raised if the variant given by A is not an array, or if the dimension specified by dim does not exist.


Variant::ArrayRedim

Variant

Description

Resizes the given variant array by changing the high bound of the rightmost dimension to the given value.

void __fastcall ArrayRedim(int highBound);

Existing elements of the array are preserved, and new elements are set to zero or empty. An EVariantError exception is raised if the variant given by A is not an array, or if there is not enough memory to resize the array.


Variant::ArrayUnLock

Variant

Description

Unlocks a variant array that was previously locked by ArrayLock.

void    __fastcall ArrayUnlock();

An EVariantError exception is raised if the Variant is not an array.


Variant::AsType

Variant

Description

Casts a Variant object to the type specified by the argument VarType.

Variant __fastcall AsType(int VarType) const;

After the call to AsType there are two Variant objects of the same type.


Variant::ChangeType

Variant	See also

Description

Changes the data type of a Variant object once it has already been instantiated.

Variant& __fastcall ChangeType(int VarType);

After the call to ChangeType this Variant is converted to type VarType.


Variant::Clear

Variant

Description

Assigns the value Unassigned to this Variant.

void __fastcall Clear();


Variant::CreateObject

Variant

Description

Creates an OLE Automation object with the programmatic identifier specified by ProgID and returns it as a Variant.

static Variant __fastcall CreateObject(const String& ProgID);

CreateObject creates a single uninitialized object of the class associated with the ProgID specified by the ProgID parameter. CreateObject is used to create an object of a specified type when the ProgID is known, and when the object is on a local or in-proc server. Only objects that are not part of an aggregate are created using CreateObject.

CreateObject is called once to create each new single instance of a class. To create multiple instance of the same class, it is recommended to use a class factory.

CreateObject returns a reference to the identifier of the interface to be used to communicate with the object. For CreateObject, this interface is of type IDispatch.

If ProgId is invalid, CreateObject throws an EOleSysError exception.


Variant::Exec

Variant	See also

Description

Exec executes an OLE procedure, function, or a property Get or Set method.

Variant __fastcall Exec(AutoCmd& cmd, Integer lcid = LOCALE_SYSTEM_DEFAULT);

Use Exec to call OLE procedures or functions. The default value for lcid is LOCALE_SYSTEM_DEFAULT. Attempts to change this value are ignored and always revert to LOCALE_SYSTEM_DEFAULT.


Variant::GetActiveObject

Variant

Description

Retrieves a reference to an IDispatch interface to a currently running, registered OLE Automation object, and returns it as a Variant.

static Variant __fastcall GetActiveObject(const String& ProgID);

Returns a reference to a the IDispatch interface of the active object for the given class indicated by ProgID. ProgID is the programmatic ID for the class of the active object from the OLE registration database.

If either the the class object or the IDispatch interface are not successfully returned, an EOleSysError exception is thrown.


Variant::GetElement

Variant	See also

Description

The Variant GetElement function is overloaded as follows:

Variant __fastcall GetElement(const int i1) const;

Variant __fastcall GetElement(const int i1, const int i2) const;

Variant __fastcall GetElement(const int i1, const int i2, const int i3) const;

Variant __fastcall GetElement(const int i1, const int i2, const int i3, const int i4) const;

Variant __fastcall GetElement(const int i1, const int i2, const int i3, const int i4, const int i5) const;

Use these the GetElement functions to access one-dimensional or multi-dimensional Variant arrays of up to 5 dimensions.


Variant::GetError

Variant

Description

Converts the Variant to a varError type and returns the integer value.

Integer __fastcall GetError() const;

See the base class TVarData for more information about varError.


Variant::IsArray

Variant	See also

Description

Returns true if the given variant is an array, false otherwise.

bool    __fastcall IsArray() const;

IsArray queries the VType of the base class TVarData for the varArray bit.


Variant::IsEmpty

Variant	See also

Description

Returns true if the Variant type code is varEmpty, false otherwise.

bool __fastcall IsEmpty() const;

IsEmpty queries the VType of the base class TVarData.


Variant::IsNull

Variant	See also

Description

Returns true if the Variant type code is varNull, false otherwise.

bool __fastcall IsNull() const;

IsArray queries the VType of the base class TVarData for the varNull bit.


Variant::OleFunction

Variant	See also

Description

OleFunction provides an alternate syntax for OLE Automation calls to Exec().

Variant OleFunction(const String& name, Variant& v0 = Variant(), Variant& v1 = Variant(), Variant& v2 = Variant(), Variant& v3 = Variant(), Variant& v4 = Variant(), Variant& v5 = Variant(), Variant& v6 = Variant(), Variant& v7 = Variant(), Variant& v8 = Variant(), Variant& v9 = Variant());

OleFunction is a wrapper for calling Exec specifically for OLE Automation object functions with an argument list of 9 or less.

Named parameters are not supported.


Variant::OleProcedure

Variant	See also

Description

OleProcedure provides alternative syntax to OLE Automation calls to Exec().

void OleProcedure(const String& name, Variant& v0 = Variant(), Variant& v1 = Variant(), Variant& v2 = Variant(), Variant& v3 = Variant(), Variant& v4 = Variant(), Variant& v5 = Variant(), Variant& v6 = Variant(), Variant& v7 = Variant(), Variant& v8 = Variant(), Variant& v9 = Variant());

OleProcedure is a wrapper for calling Exec specifically for OLE procedures with an argument list of 9 or less.

Named parameters are not supported.


Variant::OlePropertyGet

Variant	See also

Description

OlePropertyGet provides alternative syntax to OLE Automation calls to Exec().

Variant OlePropertyGet(const String& name, Variant& v0 = Variant(), Variant& v1 = Variant(), Variant& v2 = Variant(), Variant& v3 = Variant(), Variant& v4 = Variant(), Variant& v5 = Variant(), Variant& v6 = Variant(), Variant& v7 = Variant(), Variant& v8 = Variant(), Variant& v9 = Variant());

OlePropertyGet is a wrapper for calling Exec(). You can use OlePropertyGet specifically for OLE functions that read properties with an argument list of 9 items or less.


Variant::OlePropertySet

Variant	See also

Description

OlePropertySet provides an alternative syntax to OLE Automation calls to Exec().

void OlePropertySet(const String& name, Variant& v0 = Variant(), Variant& v1 = Variant(), Variant& v2 = Variant(), Variant& v3 = Variant(), Variant& v4 = Variant(), Variant& v5 = Variant(), Variant& v6 = Variant(), Variant& v7 = Variant(), Variant& v8 = Variant(), Variant& v9 = Variant());

OlePropertySet is a wrapper for calling Exec. You can use OlePropertySet specifically for OLE functions that write properties with an argument list of 9 items or less.


Variant::PutElement

Variant	See also

Description

The Variant PutElement function is overloaded as follows:

void __fastcall PutElement(const Variant& data, const int i1);

void __fastcall PutElement(const Variant& data, const int i1, const int i2);

void __fastcall PutElement(const Variant& data, const int i1, const int i2, const int i3);

void __fastcall PutElement(const Variant& data, const int i1, const int i2, const int i3, const int i4);

void __fastcall PutElement(const Variant& data, const int i1, const int i2, const int i3, const int i4, const int i5);

Use these the PutElement functions to access one-dimensional and multi-dimensional Variant arrays of up to 5 dimensions.


Variant::SetError

Variant	See also

Description

Converts the Variant to a varError type and assigns the integer err as the value of the varError.

void __fastcall SetError(const Integer err);

See the base class TVarData for more information about varError.


Variant::Type

Variant	See also

Description

Returns type code of a Variant instance.

int __fastcall Type() const;

Returns the type code of the given variant. The return value is constructed from the constants declared in the vcl\sysdefs.h header file.

The lower twelve bits of a variant type code (the bits defined by the varTypeMask bit mask) define the type of the variant. The varArray bit is set if the variant is an array of the given type. The varByRef bit is set if the variant is a reference to a value of the given type as opposed to an actual value.

The following table describes each of the variant type codes.

Variant type Return value	Contents of variant

varEmpty    = 0X0000; 	The variant is Unassigned.

varNull     = 0X0001; 	The variant is Null.

varSmallint = 0X0002; 	16-bit signed integer (type Smallint).

varInteger  = 0X0003; 	32-bit signed integer (type Integer).

varSingle   = 0X0004; 	Single-precision floating-point value (type Single).

varDouble   = 0X0005; 	Double-precision floating-point value (type Double).

varCurrency = 0X0006; 	Currency floating-point value (type Currency).

varDate     = 0X0007; 	Date and time value (type TDateTime).

varOleStr   = 0X0008; 	Reference to a dynamically allocated Unicode string.

varDispatch = 0X0009; 	Reference to an OLE automation object (an IDispatch interface pointer).

varError    = 0X000A; 	Operating system error code.

varBoolean  = 0X000B; 	16-bit boolean (type WordBool).

varVariant  = 0X000C;	Indicates another Variant.

varUnknown  = 0X000D; 	Reference to an unknown OLE object (an IUnknown interface pointer).

varByte     = 0X0011;	Indiactes an unsigned char.

varString   = 0X0100; 	Reference to a dynamically allocated string (type AnsiString).

varTypeMask = 0X0FFF;	 Indicates the type of each array element.

varArray    = 0X2000;	Indicates a Variant array.

varByRef    = 0X4000;	Indicates that the variant contains a reference as opposed to a value.

The type of a variant can be changed using the ChangeType member function.


Variant example

Variant

#include <vcl.h>

#pragma hdrstop

#include <iostream.h>

#include <oleauto.hpp>

#include <math.h>

//--------------------------------------------------------------------

void TestConstructors();

void TestAssignments();

void TestTypeChanging();

void TestOperators();

void TestArrays();

void TestOle();

//--------------------------------------------------------------------

main()

{

    TestConstructors();

    TestAssignments();

    TestTypeChanging();

    TestOperators();

    TestArrays();

    TestOle();

    return 0;

}

//--------------------------------------------------------------------

void CheckType(const Variant& v, Word type)

{

  if (v.VType == type)

    cout << "Type Check OK: ";

  else  cout << "Type Check ERROR: ";

  cout <<   "type: " << v.VType;

  cout << ", expected: " << type << endl;

}

//--------------------------------------------------------------------

void Compare(Variant &lhs, Variant &rhs)

{

  if (lhs == rhs)

    cout << "Compare OK: ";

  else

    cout << "Compare ERROR: ";

  cout <<   "lhs type: " << lhs.VType;

  cout << ", rhs type: " << rhs.VType;

  cout << ", lhs val: "  << String(lhs).c_str();

  cout << ", rhs val: "  << String(rhs).c_str() << endl;

}

//--------------------------------------------------------------------

void TestConstructors()

{

  static short smallint = 3;

  static int integer = 4;

  static float flt = 5;

  static double dbl = 6;

  static Currency currency = 7;

  static TDateTime date = String("05/11/95");

  static WordBool boolean = true;

  static Byte byte = 9;

  static wchar_t* oleStr = SysAllocString(L"Hey, welcome to the world of variant and OLE");

  Variant vEmpty;

  //can't actually construct a null

  Variant vNull;

  vNull.ChangeType(varNull);

  // by value

  Variant vSmallint(short(3));

  Variant vInteger(4);

  Variant vSingle(float(5));

  Variant vDouble(double(6));

  Variant vCurrency(Currency(7));

  Variant vDate(TDateTime(String("05/11/95")));

  Variant vBoolean(true);

  Variant vByte((Byte)9);

  Variant vString(String("This is an ANSI string, buddy!"));

  Variant vOleStr(L"Hey, welcome to the world of Variants & OLE Automation");

  Variant vDispatch(Variant::CreateObject("Word.Basic"));

  Variant vUnknown(Variant::CreateObject("Word.Basic").AsType(varUnknown));

  // by reference

  Variant vrSmallint = &smallint;

  Variant vrInteger = &integer;

  Variant vrSingle = &flt;

  Variant vrDouble = &dbl;

  Variant vrCurrency = &currency;

  Variant vrDate = &date;

  Variant vrBoolean = &boolean;

  Variant vrByte = &byte;

  Variant vrOleStr = &oleStr;

  cout << endl << "TestConstructors output:" << endl;

  CheckType(vEmpty, varEmpty);

  CheckType(vNull, varNull);

  cout << endl << "TestConstructors(byval) output:" << endl;

  CheckType(vSmallint, varSmallint);

  CheckType(vInteger, varInteger);

  CheckType(vSingle, varSingle);

  CheckType(vDouble, varDouble);

  CheckType(vCurrency, varCurrency);

  CheckType(vDate, varDate);

  CheckType(vBoolean, varBoolean);

  CheckType(vByte, varByte);

  CheckType(vString, varString);

  CheckType(vOleStr, varOleStr);

  CheckType(vDispatch, varDispatch);

  CheckType(vUnknown, varUnknown);

  cout << endl << "TestConstructors(byref) output:" << endl;

  CheckType(vrSmallint, varSmallint | varByRef);

  CheckType(vrInteger, varInteger | varByRef);

  CheckType(vrSingle, varSingle | varByRef);

  CheckType(vrDouble, varDouble | varByRef);

  CheckType(vrCurrency, varCurrency | varByRef);

  CheckType(vrDate, varDate | varByRef);

  CheckType(vrBoolean, varBoolean | varByRef);

  CheckType(vrByte, varByte | varByRef);

  CheckType(vrOleStr, varOleStr | varByRef);

  SysFreeString(oleStr);

}

//--------------------------------------------------------------------

void TestAssignments()

{

  Variant vEmpty, vNull;

  //by val

  Variant vSmallint, vInteger, vSingle, vDouble, vCurrency, vDate;

  Variant vOleStr, vDispatch, vBoolean, vByte, vString, vUnknown;

  //by ref

  Variant vrSmallint, vrInteger, vrSingle, vrDouble, vrCurrency, vrDate;

  Variant vrOleStr, vrDispatch, vrBoolean, vrByte, vrString, vrUnknown;

  static short smallint = 3;

  static int integer = 4;

  static float flt = 5;

  static double dbl = 6;

  static Currency currency = 7;

  static TDateTime date = String("05/11/95");

  static WordBool boolean = true;

  static Byte byte = 9;

  static wchar_t* oleStr = SysAllocString(L"Hey, welcome to the world of variant and OLE");

  vEmpty = Variant();

  vNull = Variant().ChangeType(varNull);

  //by value

  vSmallint = (short)3;

  vInteger = 4;

  vSingle = (float)5;

  vDouble = (double)6;

  vCurrency = Currency(7);

  vDate = (TDateTime) StrToDate(String("03/27/77"));

  vBoolean = true;

  vByte = (Byte)9;

  vString = "This is a Ansi string";

  vOleStr = L"This is an OLE string";

  vDispatch = Variant::CreateObject("Word.Basic");

  vUnknown = Variant::CreateObject("Word.Basic").AsType(varUnknown);

  // by reference

  vrSmallint = &smallint;

  vrInteger = &integer;

  vrSingle = &flt;

  vrDouble = &dbl;

  vrCurrency = &currency;

  vrDate = &date;

  vrBoolean = &boolean;

  vrByte = &byte;

  vrOleStr = &oleStr;

  cout << endl << "TestAssignments output:" << endl;

  CheckType(vEmpty, varEmpty);

  cout << endl << "TestAssignments (by val) output:" << endl;

  CheckType(vSmallint, varSmallint);

  CheckType(vInteger, varInteger);

  CheckType(vSingle, varSingle);

  CheckType(vDouble, varDouble);

  CheckType(vCurrency, varCurrency);

  CheckType(vDate, varDate);

  CheckType(vBoolean, varBoolean);

  CheckType(vByte, varByte);

  CheckType(vString, varString);

  CheckType(vOleStr, varOleStr);

  CheckType(vDispatch, varDispatch);

  CheckType(vUnknown, varUnknown);

  cout << endl << "TestAssignments (by ref) output:" << endl;

  CheckType(vrSmallint, varSmallint | varByRef);

  CheckType(vrInteger, varInteger | varByRef);

  CheckType(vrSingle, varSingle | varByRef);

  CheckType(vrDouble, varDouble | varByRef);

  CheckType(vrCurrency, varCurrency | varByRef);

  CheckType(vrDate, varDate | varByRef);

  CheckType(vrBoolean, varBoolean | varByRef);

  CheckType(vrByte, varByte | varByRef);

  CheckType(vrOleStr, varOleStr | varByRef);

  SysFreeString(oleStr);

}

//--------------------------------------------------------------------

void TestTypeChanging()

{

  Variant vSmallint = 3;

  Variant vx, vy;

  cout << endl << "TestTypeChanging output:" << endl;

  vx = vSmallint.AsType(varString);

  CheckType(vx, varString);

  vx.ChangeType(varInteger);

  CheckType(vx, varInteger);

  vy = vx.AsType(varSingle);

  CheckType(vy, varSingle);

  CheckType(vx, varInteger);

  vx.Clear();

  CheckType(vx, varEmpty);

}

//--------------------------------------------------------------------

void TestOperators()

{

  Variant vx, vy;

  cout << endl <<"TestOperators output:" << endl;

  vx = 5;

  vy = vx + 0;

  Compare(vy, vx);

  Compare(vx-0, vx);

  Compare(vx*1, vx);

  Compare(vx/1, vx);

  vx = 5;

  vy = vx + 0;

  Compare(vy, vx);

  Compare(vx-0, vx);

  Compare(vx*1, vx);

  Compare(vx/1, vx);

  vy = vx;

  Compare(vy+=0, vx);

  Compare(vy-=0, vx);

  Compare(vy*=1, vx);

  Compare(vy/=1, vx);

  vx = 5;

  vy = 46;

  vx = 2*vx + (vy-6)/2;

  Compare(vx, 30);

  vx = "hi ";

  vy = "there";

  vx += vy;

  Compare(vx, "hi there");

  //force a variant so we can test variant's operator+

  vx = 1 + 20.0 + Variant(String("300"));

  Compare(vx, 321);

  vx = 15;

  vy = (vx == 15);

  Compare(vy, true);

  vy = (vx < 15);

  Compare(vy, false);

  vy = (vx > 15);

  Compare(vy, false);

  vy = (vx != 15.3);

  Compare(vy, true);

}

//--------------------------------------------------------------------

void TestArrays()

{

  Variant a, b;

  int i, tmp;

  cout << endl <<"TestArrays output:" << endl;

  a = VarArrayCreate(OPENARRAY(int, (0, 9)), varInteger);

  b = VarArrayCreate(OPENARRAY(int, (1, 3, 0, 9)), varInteger);

  // Do it with array lock

  int* ax = (int*) a.ArrayLock();

  for (i=0; i < 10; i++)

    ax[i] = i*i;

  Compare(ax[0], 0);

  Compare(ax[9], 81);

  a.ArrayUnlock();

  //Do it again with Put/GetElement

  for (i=0; i < 10; i++)

  {

    tmp = i*i*i;

    a.PutElement(&tmp, i);

  }

  Compare(a.GetElement(0), 0);

  Compare(a.GetElement(9), 9*9*9);

  // Try a 2-dimensional array

  for (i=0; i < 10; i++)

  {

    b.PutElement(&i, 1, i);

    tmp = sqrt(i);

    b.PutElement(&tmp, 2, i);

    tmp = i*i;

    b.PutElement(&tmp, 3, i);

  }

  Compare(b.GetElement(1,0), 0);

  Compare(b.GetElement(1,9), 9);

  Compare(b.GetElement(2, 0), 0);

  Compare(b.GetElement(2, 9), 3);

  Compare(b.GetElement(3, 0), 0);

  Compare(b.GetElement(3, 9), 81);

}

//--------------------------------------------------------------------

void TestOle()

{

  Variant   wordBasic, res;

  Function  fileNew("FileNew");

  Procedure insert("Insert");

  Function  fileSaveAs("FileSaveAs");

  cout << endl << "TestOle:  check contents of test.txt" << endl;

  wordBasic = Variant::CreateObject("Word.Basic");

  res = wordBasic.Exec(fileNew <<"Normal");

  wordBasic.Exec(insert <<"This is the first line\n");

  wordBasic.Exec(insert.ClearArgs() <<"This is the second line\n");

  res = wordBasic.Exec(fileSaveAs <<"test.txt" <<3);

}


Alignment example

This code puts the check box of the TCheckBox control on the left side of its label:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

CheckBox1->Ctl3D = false;

CheckBox1->Alignment = taLeftJustify;

}

This code aligns text to the right side of a label named Label1 in response to a click on a button named RightAlign:

void __fastcall TForm1::RightAlignClick(TObject *Sender)

{

Label1->Alignment = taRightJustify;

}


AllowAllUp example

In this example, there are three speed buttons on a form. All three belong to the same group as all three have a GroupIndex value of 1. This line of code changes the AllowAllUp property to True for all three speed buttons, so it's possible that all the speed buttons in the group can be unselected at the same time:

SpeedButton3->AllowAllUp = true;


AutoSelect example

This example uses an edit box and a check box on a form. Set the caption of the check box to 'AutoSelect text'. When the user checks the check box, text is automatically selected each time the user tabs to the edit box. If the user unchecks the check box, text is no longer selected automatically when the user tabs to the edit box.

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

if (CheckBox1->Checked)

Edit1->AutoSelect = true;

else

Edit1->AutoSelect = false;

}


BevelInner example

This example uses a panel component and a button named CreateStatusLine on a form. The code moves the panel to the bottom of the form when the user clicks the button and gives the panel the appearance of a status line by changing the value of the BevelInner, BevelOuter, BevelWidth, and BorderWidth properties.

void __fastcall TForm1::CreateStatusLineClick(TObject *Sender)

{

Panel1->Align = alBottom;

    	Panel1->BevelInner = bvLowered;

    	Panel1->BevelOuter = bvRaised;

    	Panel1->BorderWidth = 1;

    	Panel1->BevelWidth = 1;

}


BevelOuter example

This code creates a lowered frame 10 pixels wide around a panel component named Panel1:

Panel1->BorderWidth = 10;

Panel1->BevelInner = bvRaised;

Panel1->BevelOuter = bvLowered;


BevelWidth example

This code alternately displays and hides the bevels of a panel when the user clicks the Button1 button:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Panel1->BevelInner = bvLowered;

Panel1->BevelOuter = bvRaised;

if (Panel1->BevelWidth == 0)

Panel1->BevelWidth = 2;

else

Panel1->BevelWidth = 0;

}


BorderStyle example

The following example puts a single-line border around the edit box, Edit1:

Edit1->BorderStyle = bsSingle;


BorderWidth example

This example uses a panel component and a button named CreateStatusLine on a form. The code moves the panel to the bottom of the form when the user clicks the button and gives the panel the appearance of a status line by changing the value of the BevelInner, BevelOuter, BevelWidth, and BorderWidth properties.

void __fastcall TForm1::CreateStatusLineClick(TObject *Sender)

{

Panel1->Align = alBottom;

Panel1->BevelInner = bvLowered;

Panel1->BevelOuter = bvRaised;

Panel1->BorderWidth = 1;

Panel1->BevelWidth = 1;

}


BoundsRect example

This code resizes a button control to twice as wide and half as high:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TRect MyRect;

MyRect = Button1->BoundsRect;

MyRect.Right = MyRect.Left + 2 * (MyRect.Right - MyRect.Left);

MyRect.Bottom = MyRect.Top + (MyRect.Bottom - MyRect.Top) / 2;

Button1->BoundsRect = MyRect;

}


Brush example

The following code sets the color of the brush used by Form1 to fill shapes drawn on it with red:

void __fastcall TForm1::MakeRedButtonClick(TObject *Sender)

{

Canvas->Brush->Color = clRed;

}

This code changes the shape, color, and pattern of a shape component:

void __fastcall TForm1::ChangeShapeClick(TObject *Sender)

{

Shape1->Shape = stEllipse;

Shape1->Brush->Color = clMaroon;

Shape1->Brush->Style = bsFDiagonal;

}


Cancel example

The following code designates a button called Button1 as a Cancel button:

Button1->Cancel = true;


CanFocus example

This example uses a group box, a label, and a button on a form. The group box contains a check box. When the application runs, the group box is disabled (Enabled is set to False). Because the group box is the parent of the check box, the user can never tab to the check box. When the user clicks the button, the caption of the label reports that the check box can not receive the input focus:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if (CheckBox1->CanFocus())

Label1->Caption = "The check box can focus";

else

Label1->Caption = "The check box cannot focus";

}

void __fastcall TForm1::FormCreate(TObject *Sender)

{

GroupBox1->Enabled = true;

}


CellRect example

This example uses a draw grid, four labels, and a button on a form. When the user clicks the button, the coordinates of the cell in the second column and first row appear in the label captions.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TRect Rectangle;

Rectangle = DrawGrid1->CellRect(3, 2);

Label1->Caption = String(Rectangle.Top) + " is the top";

Label2->Caption = String(Rectangle.Bottom) + " is the bottom";

Label3->Caption = String(Rectangle.Left) + " is the left side";

Label4->Caption = String(Rectangle.Right) + " is the right side";

}


Center example

The following code centers the image in Image1 when the user checks CheckBox1:

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

Image1->Center = CheckBox1->Checked;

}


CharCase example

This example uses an edit box and group box containing three radio buttons. When the user selects the first radio button, the text in the edit box becomes lowercase, and any text the user types in the edit box also appears in lowercase. When the user selects the second radio button, the text in the edit box becomes uppercase, and any text the user types in the edit box also appears in uppercase. When the user selects the third radio button, the text in the edit box remains unchanged, but the user can type using either upper- or lowercase characters:

void __fastcall TForm1::RadioButton1Click(TObject *Sender)

{

Edit1->CharCase = ecLowerCase;

}

void __fastcall TForm1::RadioButton2Click(TObject *Sender)

{

Edit1->CharCase = ecUpperCase;

}

void __fastcall TForm1::RadioButton3Click(TObject *Sender)

{

Edit1->CharCase = ecNormal;

}


Checked example

This example fills in a radio button at run time:

RadioButton1->Checked = true;

This example uses a main menu component that contains a menu item named SnapToGrid1 on a form. When the user chooses the Snap To Grid command, a check mark appears next to the command. When the user chooses the Snap To Grid command again, the check marks disappears:

void __fastcall TForm1::SnapToGrid11Click(TObject *Sender)

{

SnapToGrid11->Checked = !SnapToGrid11->Checked;

}


ClientHeight example

This example reduces the height of the form's client area by half when the user clicks the button on the form:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Form1->ClientHeight = Form1->ClientHeight/2;

}

Note that only the client area is halved, not the entire form.


ClassName example

This example uses a button, a label, a check box, and an edit box on a form. When the user clicks one of the controls, the name of the control's class appears in the edit box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Edit1->Text = String(Button1->ClassName());

}

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

Edit1->Text = String(CheckBox1->ClassName());

}

void __fastcall TForm1::Label1Click(TObject *Sender)

{

Edit1->Text = String(Label1->ClassName());

}


ClassParent example

This code example uses a button and a list box on a form. When the user clicks the button, the name of the button's class and the names of its parent classes are added to the list box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TClass ClassRef;

ListBox1->Clear();

ClassRef = Sender->ClassType();

while(ClassRef != NULL)

{

ListBox1->Items->Add(ClassRef->ClassName());

ClassRef = ClassRef->ClassParent();

}

}

The list box contains the following strings after the user clicks the button:

TButton

TButtonControl

TWinControl

TControl

TComponent

TPersistent

TObject


ClassType example

This example uses a button and a label on a form. When the user clicks the button, the type of the button component (TButton) appears in the caption of the label.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TClass ButtonClassType;

ButtonClassType = Button1->ClassType();

Label1->Caption = ButtonClassType->ClassName();

}


ClearSelection example

This code uses a memo control named MyMemo and a button on a form. When the user clicks the button, the text the user selected in the memo control is deleted.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

MyMemo->ClearSelection();

}


ClientOrigin example

This example displays the Y screen coordinate of the top right corner of the Button1 button client area:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

char buf[10];

itoa(Button1->ClientOrigin.y, buf, 10);

AnsiString aBuf(buf);

Edit1->Text = aBuf;

}


ClientRect example

The following code uses ClientRect to find and draw a line from the top left to the bottom right of the current form:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Canvas->MoveTo(ClientRect.Left,ClientRect.Top);

Canvas->LineTo(ClientRect.Right, ClientRect.Bottom);

}


ClientToScreen example

This example uses two edit boxes on a form. When the user clicks a point on the form, the X screen coordinate appears in Edit1, and the Y screen coordinate appears in Edit2.

void __fastcall TForm1::FormMouseDown(TObject *Sender, TMouseButton Button,	TShiftState Shift, int X, int Y)

{

TPoint P, Q;

P.x = X;	//P is the TPoint record for the form

P.y = Y;

Q = ClientToScreen(P);	//Q is the TPoint for the screen

char xCoord[40];

char yCoord[40];

itoa(Q.x, xCoord, 10);	//convert the integers to strings

itoa(Q.y, yCoord, 10);

AnsiString xString(xCoord);

AnsiString yString(yCoord);

Edit1->Text = xString + " is the X screen coordinate";

Edit2->Text = yString + " is the Y screen coordinate";

}


ClientWidth example

This example uses a button on a form. Each time the user clicks the button, the button grows 10 pixels wider.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Button1->ClientWidth = Button1->ClientWidth + 10;

}


Col example

This example uses a string grid with a label above it on a form. When the user clicks a cell in the grid, the location of the cursor is displayed in the label caption.

void __fastcall TForm1::DrawGrid1Click(TObject *Sender)

{

char rBuf[10];

char cBuf[10];

itoa(DrawGrid1->Col + 1, cBuf, 10);

itoa(DrawGrid1->Row + 1, rBuf, 10);

Label1->Caption = String("The cursor is in column ") + String(cBuf) + String(", row ") + String(rBuf);

}


ColWidths example

The following code changes the width of column 0 in the string grid called StringGrid1 to twice the default value.

DrawGrid1->ColWidths[0] = DrawGrid1->DefaultColWidth * 2;


ComponentCount example

This code uses several controls on a form, including a button and an edit box. When the user clicks the button, the code counts all the components on the form and displays the number in the Edit1 edit box. While the components are being counted, each is evaluated to see if it is a button component. If the component is a button, the code changes the font on the button face.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

AnsiString nameString("TButton");

char compBuf[10];

TButton * button;

for(int i=0; i < ComponentCount; i++)

{

//Check to see if the component is a TButton

if (Components[i]->ClassNameIs(nameString))

{

//cast the component to a TButton *

button = (TButton *)Components[i];

button->Font->Name = "Courier";

itoa(ComponentCount, compBuf, 10);

Edit1->Text = AnsiString(compBuf) + AnsiString(" components");

}

}

}


ComponentIndex example

The following code uses a button and a wide edit box on a form. When the user clicks the button, the edit box displays the index value of the button component:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

char index[10];

char *string = new char[strlen("The index of the button is ")];

itoa(Button1->ComponentIndex, index, 10);

strcpy(string, "The index of the button is ");

strcat(string, index);

Edit1->Text = string;

delete string;

}


Components example

This code uses several controls on a form, including a button and an edit box. When the user clicks the button, the code counts all the components on the form and displays the number in the Edit1 edit box. While the components are being counted, each is evaluated to see if it is a button component. If the component is a button, the code changes the font on the button face.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

AnsiString nameString("TButton");

char compBuf[10];

TButton * button;

for(int i=0; i < ComponentCount; i++)

{

//Check to see if the component is a TButton

if (Components[i]->ClassNameIs(nameString))

{

//cast the component to a TButton *

button = (TButton *)Components[i];

button->Font->Name = "Courier";

itoa(ComponentCount, compBuf, 10);

Edit1->Text = AnsiString(compBuf) + AnsiString(" components");

}

}

}


ContainsControl example

This example uses a label, a list box, and a button on a form. When the user clicks the button, the caption of the label reports that the form contains the list box:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if(Form1->ContainsControl(ListBox1))

Label1->Caption = "The form contains ListBox1";

}


ControlCount example

This example uses a group box on a form, with several radio button controls contained within the group box. The form also has an edit box and a button outside of the group box. The code sets the parent of the radio buttons to the radio group.  It then counts each control's child controls turning each of them invisible as they are counted. The total number of controls counted appears in the edit box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

RadioButton1->Parent = RadioGroup1;

RadioButton2->Parent = RadioGroup1;

RadioButton3->Parent = RadioGroup1;

for(int i=0; i < RadioGroup1->ControlCount; i++)

RadioGroup1->Controls[i]->Visible = false;

Edit1->Text = String(RadioGroup1->ControlCount) + String(" controls");

}


Controls example

This example uses a group box on a form, with several radio button controls contained within the group box. The form also has an edit box and a button outside of the group box. The code sets the parent of the radio buttons to the radio group.  It then counts each control's child controls turning each of them invisible as they are counted. The total number of controls counted appears in the edit box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

RadioButton1->Parent = RadioGroup1;

RadioButton2->Parent = RadioGroup1;

RadioButton3->Parent = RadioGroup1;

for(int i=0; i < RadioGroup1->ControlCount; i++)

RadioGroup1->Controls[i]->Visible = false;

Edit1->Text = String(RadioGroup1->ControlCount) + String(" controls");

}


Ctl3D example

The following code toggles the 3-D look of a memo control when the user clicks a button named Toggle:

void __fastcall TForm1::ToggleClick(TObject *Sender)

{

Memo1->Ctl3D = !Memo1->Ctl3D;	//Toggles the Ctl3d property of 	//Memo1

}


DefaultColWidth example

The following code changes the width of column 0 in the string grid called StringGrid1 to twice the default value.

DrawGrid1->ColWidths[0] = DrawGrid1->DefaultColWidth * 2;


DefaultDrawing example

The following code sets DefaultDrawing to False for DrawGrid1.

DrawGrid1->DefaultDrawing = false;


DefaultExt example

This example sets the default file extension to TXT, displays the Open dialog box, then assigns the filename the user selects with the dialog box to a variable the application can use to open a file:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TFileName NameOfFile;

OpenDialog1->DefaultExt = String("TXT");

if(OpenDialog1->Execute())

NameOfFile = OpenDialog1->FileName;

}

When this code runs, if the user types a filename in the File Name edit box in the Open dialog box, but doesn't specify an extension, the TXT extension is added to the filename, and the entire filename is saved in the NameOfFile variable. For example, if the user types MYNOTES as the filename, the string saved in the NameOfFile variable is MYNOTES.TXT.


DefaultRowHeight example

The following line of code changes the default height of the rows in a string grid control to 10 pixels more than the original value:

StringGrid1->DefaultRowHeight = StringGrid1->DefaultRowHeight + 10;


DragCursor example

The following code changes the DragCursor of Memo1 to crIBeam.

Memo1->DragCursor = crDrag;


Dragging example

This example uses three check boxes on a form. When the user begins dragging one of the check boxes, the color of the form changes:

void __fastcall TForm1::FormActivate(TObject *Sender)

{

CheckBox1->DragMode = dmAutomatic;

CheckBox2->DragMode = dmAutomatic;

CheckBox3->DragMode = dmAutomatic;

}

void __fastcall TForm1::FormDragOver(TObject *Sender, TObject *Source, int X, int Y, TDragState State, bool &Accept)

{

if (CheckBox1->Dragging())

Color = clAqua;

if (CheckBox2->Dragging())

Color = clYellow;

if (CheckBox3->Dragging())

Color = clLime;

}


DragMode example

This example determines whether the drag mode of the button on the form is manual. If it is, the dragging the button becomes possible.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if (Button1->DragMode == dmManual)

Button1->BeginDrag(true);

}


EditMask example

This example assigns an edit mask to the masked edit box on the form. The edit mask makes it easy to enter American telephone numbers in the edit box.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

MaskEdit1->EditMask = "!\(999\)000-0000;1";

MaskEdit1->Text = "";

MaskEdit1->AutoSelect = false;

}


Enabled example

To disable a button called FormatDiskButton,

FormatDiskButton->Enabled = false;


EndDrag example

The following code cancels the dragging of Label1 without dropping the object.

Label1->EndDrag(false);


FileName example

This example displays an Open dialog box and suggests the filename LIST.CPP to the user. Once the user selects a filename, the code displays that name in a label on the form:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

OpenDialog1->FileName = "LIST.CPP";

if(OpenDialog1->Execute())

Label1->Caption = OpenDialog1->FileName;

}


FindComponent example

To set up this example, place several components on a form, including an edit box and a button. When the user clicks the button, the code displays the value of the ComponentIndex of the edit box in the edit box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TComponent * TheComponent;

char buf[10];

TheComponent = FindComponent("Edit3");

wsprintf(buf,"%d",TheComponent->ComponentIndex);

Edit1->Text = buf;

}


FindNextPage example

The following code allows the user to select tab sheets by clicking on a button rather than a tab:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

PageControl1->ActivePage = PageControl1->FindNextPage(PageControl1->ActivePage,true,true);

}


FixedColor example

This example uses a draw grid and a button on a form. When the user clicks the button, the color of the nonscrolling (fixed) rows and columns of the draw grid changes color.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if(DrawGrid1->FixedColor == clBlue)

DrawGrid1->FixedColor = clLime;

else

DrawGrid1->FixedColor = clMaroon;

}


FixedCols example

This example uses a string grid and a button. When the user clicks the button, a message dialog box appears informing the user that a fixed column number of 2 is recommended. The dialog box also offers the user an opportunity to accept the recommended number if the number of fixed columns isn't already 2. If the user chooses Yes, the number of fixed columns changes to 2.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

int Check;

if(DrawGrid1->FixedCols != 2)

Check = Application->MessageBox("2 fixed columns are recommended!  Change?", "Incorrect Columns", MB_YESNOCANCEL);

if(Check == IDYES)

DrawGrid1->FixedCols = 2;

}


FixedRows example

This example uses a string grid and three radio buttons on a form. With the Object Inspector, specify the following event handler for all OnClick events of the three radio buttons. As the user selects different radio buttons, the number of fixed rows in the string grid changes.

void __fastcall TForm1::RadioButton1Click(TObject *Sender)

{

if(RadioButton1->Checked)

StringGrid1->FixedRows = 1;

else if (RadioButton2->Checked)

StringGrid1->FixedRows = 2;

else if (RadioButton3->Checked)

StringGrid1->FixedRows = 3;

}


Glyph example

This example uses a bitmap button on a form. When the application runs and the form is created, a bitmap is placed on the bitmap button.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

BitBtn1->Glyph->LoadFromFile("TIME.BMP");

}

These lines of code load a four-image bitmap into the Glyph property of a speed button, and specify the appropriate value for the NumGlyphs property:

SpeedButton1->Glyph->LoadFromFile("MYBITMAP.BMP");

SpeedButton1->NumGlyphs = 4;


GridLineWidth example

This example includes a draw grid on a form. When the application runs and the form is created, the width of the lines on the draw grid changes if the default column width of the grid is over 90 pixels wide:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

if(DrawGrid1->DefaultColWidth > 90)

DrawGrid1->GridLineWidth = 2;

else

DrawGrid1->GridLineWidth = 1;

}


GridWidth example

This example uses a string grid and a label on a form. The label reports the width of the grid.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

for(int ARow = 1; ARow < StringGrid1->RowCount; ARow++)

for(int ACol = 1; ACol < StringGrid1->ColCount; ACol++)

StringGrid1->Cells[ARow][ACol] = "C++Builder";

char buf[10];

itoa(StringGrid1->GridWidth, buf, 10);

Label1->Caption = String(buf) + " pixels";

}


GroupIndex example

This code assures that the three speed buttons work together as a group:

SpeedButton1->GroupIndex = 1;

SpeedButton2->GroupIndex = 1;

SpeedButton3->GroupIndex = 1;


Handle example

The following code uses the Windows API function ShowWindow to display Form2 as an icon, but does not activate it.

ShowWindow(Form2->Handle, SW_SHOWMINIMIZED);


HandleAllocated example

The following code displays a message if the the handle of GroupBox1 does not exist.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if(!GroupBox1->HandleAllocated())

Label1->Caption = String("Handle not allocated.");

}


HandleNeeded example

The following code creates a window handle for Button1:

Button1->HandleNeeded();


Height example

The following code doubles the height of a Memo control:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Memo1->Height = Memo1->Height * 2;

}


Hide example

This code uses a button and a timer on a form. When the user clicks the button, the form disappears for the period of time specified in the Interval property of the timer control, then the form reappears:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Timer1->Enabled = true;

Hide();

}

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

Visible = true;

Timer1->Enabled = false;

}


HideSelection example

This example uses an edit box and a memo on a form. When the user jumps from one control to the other, selected text remains selected in the memo, but not in the edit box.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

Edit1->HideSelection = true;

Memo1->HideSelection = false;

}


Hint example

This example uses an edit box and a list box on a form. Items are added to the list box and a Help Hint is assigned to both controls. The last statement enables the Help Hints for the entire application.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

Edit1->Hint = "Enter your name";

Edit1->ShowHint = true;

char string[10];

char index[3];

for(int i = 1; i <= 10; i++)

{

itoa(i, string, 10);

strcpy(string, "Item");

itoa(i, index, 10);

strcat(string, index);

ListBox1->Items->Add(string);

}

Hint = "Select an item";

ShowHint = true;

Application->ShowHint = true;

}


Images example

The following example sets the tree views Images property to ImageList1.

TreeView1->Images = ImageList1;


InsertControl example

This example uses a button and two group boxes.  When the user clicks the button, the other group box becomes the parent of the button, so the button moves inside the other group box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if (Button1->Parent == GroupBox1)

{

GroupBox1->RemoveControl(Button1);

GroupBox2->InsertControl(Button1);

}

else

{

GroupBox2->RemoveControl(Button1);

GroupBox1->InsertControl(Button1);

}

}


IntegralHeight example

This example uses a list box on a form. To try it, enter as many strings in the Items property as you like using the Object Inspector. When the application runs, the list box displays only entries that fit completely in the vertical space, and the bottom of the list box moves up to the bottom of the last string in the list box if the form is less than 300 pixels in height:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

if (Height < 300)

ListBox1->IntegralHeight = true;

else

ListBox1->IntegralHeight = false;

}


Invalidate example

The following code invalidates Form1.

Form1->Invalidate();


IsMasked example

This example tests the masked edit box to determine if it has an edit mask. If it doesn't an edit mask is assigned. The edit mask is one for dates in the MM/DD/YY format:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if(!MaskEdit1->IsMasked)

MaskEdit1->EditMask = "!99/99/00;1;_";

}


ItemHeight example

This example uses a list box and a button on a form. Enter as many strings in the list box as you like using the property editor of the Items property in the Object Inspector. When the user clicks the button on the form, the amount of vertical space allotted to each item in the list box changes.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

ListBox1->Style = lbOwnerDrawFixed;

ListBox1->ItemHeight = 30;

}


Items example

The following example changes the caption of the first item in the list view.

ListView1->Items->Item[0]->Caption = String("NewItemName");

The following example demonstrates how to add nodes andchild nodes to a TTreeView control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

//Adds a root node

TreeView1->Items->Add(TreeView1->Selected, "RootTreeNode1");

//Sets MyTreeNode to first node in

//tree view and adds a child node to it

TTreeNode *MyTreeNode1 = TreeView1->Items->Item[0];

TreeView1->Items->AddChild(MyTreeNode1,"ChildNode1");

//Adds a root node

TreeView1->Items->Add(TreeView1->Selected, "RootTreeNode2");

//Sets MyTreeNode to third node in

//tree view and adds a child node to it

TTreeNode *MyTreeNode2 = TreeView1->Items->Item[2];

TreeView1->Items->AddChild(MyTreeNode2,"ChildNode2");

//Sets MyTreeNode to fourth node in

//tree view and adds a child node to it

MyTreeNode2=TreeView1->Items->Item[3];

TreeView1->Items->AddChild(MyTreeNode2,"ChildNode2a");

//Sets MyTreeNode to fifth node in

//tree view and adds a child node to it

MyTreeNode2 = TreeView1->Items->Item[4];

TreeView1->Items->Add(MyTreeNode2,"ChildNode2b");

//add another root node

TreeView1->Items->Add(TreeView1->Selected, "RootTreeNode3");

}


LargeChange example

This code determines that when the user clicks the scroll bar on either side of the scroll box, the scroll box moves 100 positions on the scroll bar:

ScrollBar1->LargeChange = 100;


LargeImages example

The following example sets the list view's LargeImages property to ImageList1.

ListView1->LargeImages = ImageList1;


Layout example

This example uses a bitmap button on a form that has a bitmap specified as the value of its Glyph property. When the user clicks the bitmap button, the bitmap randomly changes its position on the button:

void __fastcall TForm1::BitBtn1Click(TObject *Sender)

{

int rNum = rand() % 4;

switch(rNum)

{

case 0:

BitBtn1->Layout = blGlyphLeft;

break;

case 1:

BitBtn1->Layout = blGlyphRight;

break;

case 2:

BitBtn1->Layout = blGlyphTop;

break;

case 3:

BitBtn1->Layout = blGlyphBottom;

break;

default:

ShowMessage("Unhandled case");

}

}


LeftCol example

This line of code positions the fourth column of a string grid at the left edge of the grid:

StringGrid1->LeftCol = 3;


Margin example

This example uses a moderately large bitmap button on a form. When the application runs, a bitmap (or glyph) is loaded on to the button, the bitmap appears on the right side of the button, and bitmap is placed 30 pixels from the right edge of the bitmap button.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

BitBtn1->Glyph->LoadFromFile("TIME.BMP");

BitBtn1->Layout = blGlyphRight;

BitBtn1->Margin = 30;

}


MaxLength example

The following example sets the maximum number of characters for an edit box to 80:

Edit1->MaxLength = 80;


ModalResult example

The following methods in a form are used as a modal dialog box. The methods cause the dialog box to terminate when the user clicks either the OK or Cancel button, returning mrOK or mrCancel from ShowModal, respectively:

void __fastcall TOKRightDlg::OKBtnClick(TObject *Sender)

{

ModalResult = mrOk;

}

void __fastcall TOKRightDlg::CancelBtnClick(TObject *Sender)

{

ModalResult = mrCancel;

}

You could also set the ModalResult value to mrOk for the OK button and mrCancel for the Cancel button to accomplish the same thing. When the user clicks either button, the dialog box closes.


Modified example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if (Edit1->Modified == true)

{

Application->MessageBox("Edit box text was modified",

"modified",MB_OK);

Edit1->Modified = false;

}

else

Application->MessageBox("Edit box text was not modified",

"not modified",MB_OK);

}


MultiSelect example

This line of code ensures that the user can select multiple items in a list box:

ListBox1->MultiSelect = true;


Name example

The following code lists the names of all the components of Form1 in a list box.

for(int i = 0; i < Form1->ComponentCount; i++)

ListBox1->Items->Add(Form1->Components[i]->Name;


NumGlyphs example

This example uses a speed button and a label on a form. When the example runs, the number of images in the specified bitmap appears as the caption of the label.

void __fastcall TForm1::FormActivate(TObject *Sender)

{

SpeedButton1->Glyph->LoadFromFile("TIME.BMP");

Label1->Caption = String(SpeedButton1->NumGlyphs) + String(" image(s)");

}


OnChanging example

The following code prevents the tab from changing:

void __fastcall TForm1::TabControl1Changing(TObject *Sender, bool &AllowChange)

{

AllowChange = false;

}


OnDblClick example

This example notifies the user that the form was double-clicked.

void __fastcall TForm1::FormDblClick(TObject *Sender)

{

Application->MessageBox("You double-clicked the form", "Double-Click Message", MB_OK);

}


OnEnter example

This example uses an edit box and a memo control on a form. When either the edit box or the memo is the active control, it is colored yellow. When the active control becomes inactive, the color of the control returns to the Windows system color for a window.

void __fastcall TForm1::Edit1Enter(TObject *Sender)

{

Edit1->Color = clYellow;

}

void __fastcall TForm1::Edit1Exit(TObject *Sender)

{

Edit1->Color = clWindow;

}

void __fastcall TForm1::Memo1Enter(TObject *Sender)

{

Memo1->Color = clYellow;

}

void __fastcall TForm1::Memo1Exit(TObject *Sender)

{

Memo1->Color = clWindow;

}


OnExit example

This example uses an edit box and a memo control on a form. When either the edit box or the memo is the active control, it is colored yellow. When the active control becomes inactive, the color of the control returns to the Windows system color for a window.

void __fastcall TForm1::Edit1Enter(TObject *Sender)

{

Edit1->Color = clYellow;

}

void __fastcall TForm1::Edit1Exit(TObject *Sender)

{

Edit1->Color = clWindow;

}

void __fastcall TForm1::Memo1Enter(TObject *Sender)

{

Memo1->Color = clYellow;

}

void __fastcall TForm1::Memo1Exit(TObject *Sender)

{

Memo1->Color = clWindow;

}


OnKeyPress example

This event handler displays a message dialog box specifying which key was pressed:

void __fastcall TForm1::FormKeyPress(TObject *Sender, char &Key)

{

char keyString[25];

strcpy(keyString, &Key);

strcat(keyString, " Was Pressed");

Application->MessageBox(keyString , "Message Box", MB_OK);

}


OnKeyUp example

The following code changes a form's color to aqua when a key is pressed. When the key is released, the form's color reverts to the original color. Note that the KeyPreview property of the form must be set to true to capture all key presses, even if a control has focus:

//In the declarations section of the form

TColor FormColor;

void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key,

TShiftState Shift)

{

FormColor = Form1->Color;

Form1->Color = clAqua;

}

void __fastcall TForm1::FormKeyUp(TObject *Sender, WORD &Key, TShiftState Shift)

{

Form1->Color = FormColor;

}


OnMouseMove example

The following code updates two labels when the mouse pointer is moved. The code assumes you have two labels on the form, lbHorz and lbVert. If you attach this code to the OnMouseMove event of a form, lbHorz continually displays the horizontal position of the mouse pointer, and lbVert continually displays the vertical position of the mouse pointer while the pointer is over the form.

void __fastcall TForm1::FormMouseMove(TObject *Sender, TShiftState Shift, int X,

int Y)

{

char xPos[10];

char yPos[10];

itoa(X, xPos, 10);

itoa(Y, yPos, 10);

lbHorz->Caption = xPos;

 	lbVert->Caption = yPos;

}


OnMouseUp example

The following code draws a rectangle when the user presses a mouse button, moves the mouse, and releases the mouse button. When the mouse button is released, the rectangle appears on the form's canvas. Its top-left and bottom-right corners are defined by the location of the mouse pointer when the user pressed and released the mouse button.

int StartX, StartY;  //Declare in interface section of form's unit

void __fastcall TForm1::FormMouseDown(TObject *Sender, TMouseButton Button,

TShiftState Shift, int X, int Y)

{

StartX = X;

StartY = Y;

}

void __fastcall TForm1::FormMouseUp(TObject *Sender, TMouseButton Button,

TShiftState Shift, int X, int Y)

{

Form1->Canvas->Rectangle(StartX, StartY, X, Y);

}


OnResizeRequest example

The following code resizes the rich edit control to accomodate growing or shrinking lines of text:

RichEdit1->BoundsRect = Rect;


OnScroll example

The following code repositions the thumb tab position by varying amounts. If Page Up was pressed, the box moves up only one. If Page Down was pressed, the box moves down 10. This shows how you can use the OnScroll event handler to move the thumb tab by different increments than specified by the LargeChange and SmallChange properties.

void __fastcall TForm1::ScrollBar1Scroll(TObject *Sender,TScrollCode ScrollCode, int &ScrollPos)

{

char scrString[5];

if(ScrollCode == scPageUp)

ScrollPos = ScrollPos - 1;

else if(ScrollCode == scPageDown)

ScrollPos = ScrollPos + 10;

itoa(ScrollPos, scrString, 10);

Label1->Caption = scrString;

}


Paragraph example

The following example sets the numbering property of the currently selected paragraph in RichEdit1.  The nsBullet style means that the paragraph is indented sufficiently for bullets.

RichEdit1->Paragraph->Numbering = TNumberingStyle(nsBullet);


ParentColor example

This code uses a label control and a timer component on the form. When the OnTimer event occurs, the label turns red if the label's ParentColor property is True. If the ParentColor property is False, ParentColor is set to True. The result is the label flashes red on and off. Every other time an OnTimer event occurs, the label turns red. The other times, the label assumes the color of its parent, Form1.

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

if(Label1->ParentColor)

Label1->Color = clRed;

else

Label1->ParentColor = true;

}


ParentCtl3D example

This code uses a group box and a button on a form. The code displays the group box in two dimensions when the user clicks the button:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if (GroupBox1->ParentCtl3D == true)

{

GroupBox1->ParentCtl3D = false;

GroupBox1->Ctl3D = false;

}

}


ParentFont example

This example uses a timer component and a label control. When an OnTimer event occurs and the label uses its parent's font, the code changes the label's ParentFont property to False and changes the label's font size to 30 points. When an OnTimer event occurs and the label doesn't use its parent's font, the code sets its ParentFont to true. The result is that the label's font grows and shrinks alternately, each time an OnTimer event occurs.

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

if(Label1->ParentFont == true)

Label1->Font->Size = 30;

else

Label1->ParentFont = true;

}


ParentShowHint example

This example uses an edit box, a memo, and a check box on a form. For each of these controls, the ParentShowHint property is True, the default value. When the code runs, the ShowHint property of the form is set to True and hints are assigned to each control. Because each control looks to its parent, the form, to find out whether to display a Help Hint, and because the form's ShowHint property is True, the Help Hints are available.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

ShowHint = true;

Edit1->Hint = "Enter text";

Memo1->Hint = "Enter lots of text";

CheckBox1->Hint = "Check or uncheck me";

}


PasswordChar example

The following code displays asterisks for each character in an edit box called Button1:

Edit1->PasswordChar = '*';


Picture example

This example uses two picture components. When the form first appears, two bitmaps are loaded into the picture components and stretched to fit the size of the components. To try this code, substitute names of bitmaps you have available.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

Image1->Stretch = true;

Image2->Stretch = true;

Image1->Picture->LoadFromFile("BITMAP1.BMP");

Image2->Picture->LoadFromFile("BITMAP2.BMP");

}


PopupMenu example

This example assigns the pop-up menu named MyPopupMenu to the form:

void __fastcall TForm1::FormActivate(TObject *Sender)

{

PopupMenu = MyPopupMenu;

}


ReadOnly example

This code toggles the read-only state of an edit box each time the user double-clicks the form:

void __fastcall TForm1::FormActivate(TObject *Sender)

{

Edit1->Left = 2;

Edit1->Top = 2;

Edit1->ReadOnly = true;

Edit1->Text = "Change Me";

Canvas->TextOut(10, 40, "Double-click form to toggle read-only state");

}

void __fastcall TForm1::FormDblClick(TObject *Sender)

{

Edit1->ReadOnly = !Edit1->ReadOnly;

}


RemoveComponent example

The following code removes Button2 from the Components list of Form1.

Form1->RemoveComponent(Button2);


RemoveControl example

This example uses a button and two group boxes.  When the user clicks the button, the other group box becomes the parent of the button, so the button moves inside the other group box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if (Button1->Parent == GroupBox1)

{

GroupBox1->RemoveControl(Button1);

GroupBox2->InsertControl(Button1);

}

else

{

GroupBox2->RemoveControl(Button1);

GroupBox1->InsertControl(Button1);

}

}


Row example

This examples uses a string grid with a label above it on a form. When the user clicks a cell in the grid, the location of the cursor is displayed in the caption of the label.

void __fastcall TForm1::DrawGrid1Click(TObject *Sender)

{

char cBuf[10];

char rBuf[10];

itoa(DrawGrid1->Col, cBuf, 10);

itoa(DrawGrid1->Row, rBuf, 10);

Label1->Caption = String("The cursor is in column ") + String(cBuf) +  ", row " + String(rBuf);

}


RowCount example

This example uses a draw grid and a button. When the user clicks the button, the number of columns and rows change:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

DrawGrid1->ColCount = 7;

DrawGrid1->RowCount = 11;

}


RowHeights example

This example uses a string grid and a button. When the user clicks the button, the number of columns and rows change, and the first column and row in the grid are sized differently from the rest of the columns and rows:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

DrawGrid1->ColCount = 7;

DrawGrid1->RowCount = 11;

DrawGrid1->RowHeights[0] = 35;

DrawGrid1->ColWidths[0] = 90;

}


ScaleBy example

This example makes your form 50 percent larger:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

caleBy(150, 100);

}


ScreenToClient example

The following code converts the origin of the screen (0, 0) to the client coordinates of Button2.

TPoint ScreenOrgin, ClientPoint;

ScreenOrgin.x = 0;

ScreenOrgin.y = 0;

ClientPoint = Button2->ScreenToClient(ScreenOrgin);


ScrollBars example

The following example adds a scroll bar to the bottom of memo control Memo1:

Memo1->ScrollBars = ssHorizontal;


ScrollBy example

This example uses a timer and several controls of your choosing on a form. When the application runs, the controls on the form appear to slide down and off to the right. This is because the contents of the form are scrolling both down and to the right by one pixel each time a timer event occurs:

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

ScrollBy(1,1);

}

void __fastcall TForm1::FormActivate(TObject *Sender)

{

Timer1->Interval = 1;

}


Selected example

The following code deletes the selected item in the tree view.

TreeView1->Selected->Delete();


Selection example

The following code selects the rectangle containing rows 1 through 4, and columns 2 and 3.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TGridRect myRect;

myRect.Left = 3;

myRect.Top = 1;

myRect.Right = 2;

myRect.Bottom = 4;

DrawGrid1->Selection = myRect;

}


SendToBack example

This example uses two forms. When the user clicks the button on Form2, it moves Form2 behind the other form and is no longer the active form:

void __fastcall TForm2::Button1Click(TObject *Sender)

{

SendToBack();

}

In this example, the parent of the two forms is the application itself.


SetBounds example

The following code doubles the size of a button control when the user clicks it:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Button1->SetBounds(Left, Top, Height * 2, Width * 2);

}

Note that you could use the following code instead, but each click would result in the button being redrawn twice: once to change the height, and once to change the width:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Button1->Height = Button1->Height * 2;

Button1->Width = Button1->Width * 2;

}


SetFocus example

When the user clicks the button on this form, the list box becomes the active control and receives the input focus:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

ListBox1->SetFocus();

}


SetSelTextBuf example

This example uses a button and an edit box on a form. When the user selects text in the edit box and clicks the button, new text replaces the selected text.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Edit1->SetSelTextBuf("You clicked the button");

}

//---------------------------------------------------------------------------

void __fastcall TForm1::FormActivate(TObject *Sender)

{

  Button1->Caption = "Click me";

}


SetTextBuf example

This example uses a button and an edit box on a form. When the user clicks the button, text appears in the edit box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Edit1->SetTextBuf("You clicked the button");

}

void __fastcall TForm1::FormActivate(TObject *Sender)

{

Button1->Caption = "Click me";

}


Show example

This code puts away the current form and displays another:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Form1->Hide();

Form2->Show();

}

To run this example you must include the header file for Form2.


ShowColumnHeaders example

The following example will hide the column headers of the list view.

ListView1->ShowColumnHeaders = false;


SmallChange example

This code determines that when the user clicks an arrow on the scroll bar, the thumb tab moves 10 positions on the scroll bar:

ScrollBar1->SmallChange = 10;


SmallImages example

The following example sets the list view's SmallImages property to ImageList1.

ListView1->SmallImages = ImageList1;


Sorted example

This example uses an edit box, a list box, and two buttons on a form. The buttons are named Add and Sort. When the user clicks the Add button, the text in the edit box is added to the list in the list box. When the user clicks the Sort button, the list in the list box is sorted and remains sorted, even if additional strings are added:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

ListBox1->Items->Add("Not");

ListBox1->Items->Add("In");

ListBox1->Items->Add("Alphabetical");

ListBox1->Items->Add("Order");

}

void __fastcall TForm1::AddClick(TObject *Sender)

{

ListBox1->Items->Add(Edit1->Text);

}

void __fastcall TForm1::SortClick(TObject *Sender)

{

ListBox1->Sorted = true;

}


Spacing example

This example loads a bitmap from a file when the form is created and places the bitmap 20 pixels from the right side of the button text:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

BitBtn1->Glyph->LoadFromFile("TIME.BMP");

BitBtn1->Layout = blGlyphLeft;

BitBtn1->Spacing = 20;

}


StateImages example

The following example sets the StateImages property of the tree view to ImageList1.

TreeView1->StateImages = ImageList1;


Stretch example

This example uses an image component on a form. When the form is created, the specified image is loaded and stretched to fit the boundaries of the image component.

void __fastcall TForm1::FormCreate(TObject *Sender)

{

Image1->Stretch = true;

Image1->Picture->LoadFromFile("TIME.BMP");

}


Style example

This example uses a list box and a check box. When the user checks the check box, the list box becomes an fixed owner-draw list box. When the user unchecks the check box, the list box becomes a standard list box:

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

if (CheckBox1->Checked)

ListBox1->Style = lbOwnerDrawFixed;

else

ListBox1->Style = lbStandard;

}

This example uses a bitmap button and a check box on a form. When the user checks the check box, the bitmap button assumes the new bitmap style. When the user unchecks the check box, the bitmap button takes on the Windows 3.1 look:

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

if(CheckBox1->Checked)

BitBtn1->Style = bsNew;

else

BitBtn1->Style = bsWin31;

}


TabOrder example

This example ensures that the check box on the form is the first in the tab order, and therefore, the active control whenever the form appears, no matter how many other controls are on the form:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

CheckBox1->TabStop = true;

CheckBox1->TabOrder = 0;

}


Tabs example

This example uses a tab set control and a memo control. When the user types a line in the memo control, the line is added as a new tab on the tab set control. Each time the user presses Enter in the memo control, a new tab is created in the tab set control:

void __fastcall TForm1::Memo1Change(TObject *Sender)

{

TabControl1->Tabs = Memo1->Lines;

}


TabStop example

This code removes ListBox1 from the tab order, so that the user can't use the Tab key to get to the list box:

ListBox1->TabStop = false;


TopItem example

The following example adds the caption for the first item in the list view to the list box.

ListBox1->Items->Add(ListView1->TopItem->Caption);

Note:  To run this example ViewStyle must be set to vsReport or VsList.


TopRow example

This code uses a draw grid and a button on a form. When the user clicks the button, the last row of the draw grid becomes the top row:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

DrawGrid1->TopRow = DrawGrid1->RowCount;

}


Transparent example

This code makes a label transparent:

Label1->Transparent = True;


Update example

When this line of code runs, Windows repaints EditBox1:

Edit1->Update();


VisibleColCount example

This example uses a draw grid, two labels, and a button on a form. When the user clicks the button, the number of rows and columns, excluding partial and fixed ones, are reported in the captions of the two labels:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

char rBuf[10];

char cBuf[10];

itoa(DrawGrid1->VisibleRowCount, rBuf, 10);

itoa(DrawGrid1->VisibleColCount, cBuf, 10);

Label1->Caption = String(rBuf) + " rows";

Label2->Caption = String(cBuf) + " columns";

}


VisibleRowCount example

This example uses a draw grid, two labels, and a button on a form. When the user clicks the button, the number of rows and columns, excluding partial and fixed ones, are reported in the captions of the two labels:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

char rBuf[10];

char cBuf[10];

itoa(DrawGrid1->VisibleRowCount, rBuf, 10);

itoa(DrawGrid1->VisibleColCount, cBuf, 10);

Label1->Caption = String(rBuf) + " rows";

Label2->Caption = String(cBuf) + " columns";

}


WantReturns example

This example uses a memo and a check box on a form. If the check box is checked, the user can enter return characters into text entered in the memo. If the check box is unchecked, return characters aren't entered into the memo, but go to the form.

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

if (CheckBox1->Checked)

Memo1->WantReturns = true;

else

Memo1->WantReturns = false;

}


WantTabs example

This example uses a memo and a check box on a form. When the check box is checked, the user can enter tab characters into the memo's text. When the check box is unchecked, the user can't enter tab characters into the text, but can use the Tab key to move between the memo and the check box controls.

void __fastcall TForm1::CheckBox1Click(TObject *Sender)

{

if (CheckBox1->Checked)

Memo1->WantTabs = true;

else

Memo1->WantTabs = false;

}


Width example

The following code doubles the width of a button:

Button1->Width = Button1->Width * 2;


WordWrap example

This example allows text a user enters in the Memo1 control to wrap to the next line, if the control is large enough to hold the text:

Memo1->WordWrap = true;


TApplication::CreateForm example

The following code creates Form2 of type TForm2.

Application->CreateForm(__classid(TForm2), &Form2);


TApplication::ExeName example

This code displays the current name of the application's .EXE file in a label control when the user clicks the button:

void __Fastcall TForm1::Button1Click(TObject *Sender);

{

  Label1->Caption = Application->ExeName;

}

For example, if the application name is C:\Bcb\WORK\MYAPP.EXE, that entire string appears in the label control.


TApplication::HandleException example

The following code uses the default error handling:

try

  // Some code that may produce an exception goes here

catch (Exception &exception)

{

  Application->HandleException(Sender);

}


TApplication::HandleMessage example

The following code demonstrates handling windows messages with HandleMessage():

void __fastcall TForm1::FormCreate(TObject* Sender)

{

  Button3->Caption = "Ignore Messages";

  Button3->Caption = "Handle Message";

  Application->OnIdle = MyIdleHandler;

}

void __fastcall TForm1::MyIdleHandler(TObject* Sender, bool &done)

{

  // This tells TApplication not to wait for a message

  done = false;

}

void __fastcall TForm1::Button1Click(TObject* Sender)

{

  int i = 0,

      j = 0,

      x,

      y;

  while (i < 64000) {

    Randomize();

    while (j < 64000) {

      y = random(j);

      j++;

    }

    x = random(i);

    i++;

  }

  Canvas->TextOut(10, 10, "The Button1Click handler is finished");

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

   int i = 0,

       j = 0,

       x,

       y;

  while (i < 64000) {

    Randomize();

    while (j < 64000) {

       y = random(j);

       j++;

       Application->HandleMessage();

    }

    x = random(i);

    i++;

  }

  Canvas->TextOut(10, 10, "The Button2Click handler is finished");

}


TApplication::HelpCommand example

This example uses a bitmap button on a form. When the user clicks the button, the Help contents screen of the specified Help file appears.

void __fastcall TForm1::BitBtn1Click(TObject* Sender)

{

  Application->HelpFile = "MyHelp.hlp";

  Application->HelpCommand(HELP_CONTENTS, 0);

}


TApplication::HelpFile example

To specify the MYHELP.HLP file as the Help file for your application, use this line of code:

Application->HelpFile = "MYHELP.HLP";


TApplication::HintColor example

This example includes a control (such as a TButton) that has a Hint property value (such as "This is a hint.") and has its ShowHint property value set to True. When the application runs and the user places the mouse cursor over the control, a Help Hint appears for the control in an aqua hint box after a delay of 1000 milliseconds:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->ShowHint = true;

  Application->HintColor = clAqua;

  Application->HintPause = 1000;

}


TApplication::HintPause example

This example includes a control (such as a TButton) that has a Hint property value (such as "This is a hint.") and has its ShowHint property value set to True. When the application runs and the user places the mouse cursor over the control, a Help Hint appears for the control in an aqua hint box after a delay of 1000 milliseconds:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->ShowHint = true;

  Application->HintColor = clAqua;

  Application->HintPause = 1000;

}


TApplication::Icon example

This line of code uses the icon in the MYAPP.ICO file for the application's icon:

Application->Icon->LoadFromFile("MYAPP.ICO");


TApplication::MessageBox example

This example uses a button and a label on a form. When the user clicks the button, a message box appears. When the user responds to the message box, the button selected is reported in the caption of the label:

void __fastcall TForm1::Button1Click(TObject* Sender)

{

  int button;

  button = Application->MessageBox("Welcome to C++ Builder", "Message Box", MB_OKCANCEL +

    MB_DEFBUTTON1);

 if (button == IDOK)

   Label1->Caption = "You chose OK.";

 if (button == IDCANCEL)

   Label1->Caption = "You chose Cancel.";

}


TApplication::NormalizeTopMosts example

The following code normalizes topmost forms before calling the MessageBox function in the WinProcs unit. After the message box is closed, the topmost forms are restored.

{

  Application->NormalizeTopMosts();

  MessageBox(Form1->Handle, "This should be on top.", "Message Box", MB_OK);

  Application->RestoreTopMosts();

}


TApplication::ProcessMessages example

This example uses two buttons that are long enough to accommodate lengthy captions on a form. When the user clicks the button with the caption Ignore Messages, the code begins to generate a long series of random numbers. If the user tries to resize the form while the handler is running, nothing happens until the handler is finished. When the user clicks the button with the caption Process Messages, more random numbers are generated, but Windows can still respond to a series of mouse events, such as resizing the form.

Note:	How quickly these event handlers run depends on the microprocessor of your computer. A message appears on the form informing you when the handler has finished executing.

void __fastcall TForm1::FormCreate(TObject* Sender)

{

  Button3->Caption = "Ignore Messages";

  Button3->Caption = "Handle Message";

}

void __fastcall TForm1::Button1Click(TObject* Sender)

{

  int i = 0,

      j = 0,

      x,

      y;

  while (i < 64000) {

    Randomize();

    while (j < 64000) {

      y = random(j);

      j++;

    }

    x = random(i);

    i++;

  }

  Canvas->TextOut(10, 10, "The Button1Click handler is finished");

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

   int i = 0,

       j = 0,

       x,

       y;

  while (i < 64000) {

    Randomize();

    while (j < 64000) {

       y = random(j);

       j++;

       Application->ProcessMessages();

    }

    x = random(i);

    i++;

  }

  Canvas->TextOut(10, 10, "The Button2Click handler is finished");

}


TApplication::Restore example

This example uses a timer on a form. When the application runs and the user minimizes the application, the application returns to its normal size when an OnTimer event occurs:

void __fastcall TForm1::Timer1Timer(TObject* Sender)

{

  Application->Restore();

}


TApplication::RestoreTopMosts example

The following code normalizes topmost forms before calling the MessageBox function in the WinProcs unit. After the message box is closed, the topmost forms are restored.

{

  Application->NormalizeTopMosts();

  MessageBox(Form1->Handle, "This should be on top.", "Message Box", MB_OK);

  Application->RestoreTopMosts();

}


TApplication::ShowHint example

This example uses an edit box on a form. When the application runs and the user places the mouse pointer over the edit box, a Help Hint in an aqua box appears:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  Application->ShowHint = true;

  Application->HintColor = clAqua;

  Application->HintPause = 1000;

  Edit1->ShowHint = true;

  Edit1->Hint = "Enter your name";

}


TApplication::Terminated example

The application calls the ProcessMessages() method if the application has not received the message from Windows to quit executing:

if (Application->Terminated = false) {

  Application->ProcessMessages();

  ...

}


TApplication::Title example

void __Fastcall TForm1::FormCreate(TObject *Sender);

{

  Application->Title = "My Incredible Application";

}


TBevel::Shape example

This code uses a bevel control and a button. When the user clicks the button, the bevel becomes a raised frame:

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Bevel1->Shape = bsFrame;

Bevel1->Style = bsRaised;

}


TBevel::Style example

This example uses a bevel and a check box on a form. When the check box is checked, the bevel is raised. When the check box is unchecked, the bevel is lowered:

void __fastcall TForm1::CheckBoxClick(TObject *Sender)

{

if(CheckBox1->Checked)

{

Bevel1->Style = bsRaised;

}

else

{

Bevel1->Style = bsLowered;

}

}


TBitmap::Canvas example

The following example converts an icon to a bitmap for use as the bit button's glyph when the user clicks on Button1. Since it uses the Extraction Windows API function, ShellApi must be added to the user clause of the unit.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

    TPicture* Picture1 = new TPicture();

    TIcon *Icon1 = new TIcon();

    Icon1->LoadFromFile("c:\\windows\\help.ico");

    Picture1->Icon = Icon1;

    BitBtn1->Glyph->Width = Icon1->Width;

    BitBtn1->Glyph->Height = Icon1->Height;

    BitBtn1->Width = Icon1->Width;

    BitBtn1->Height = Icon1->Height;

    BitBtn1->Glyph->Canvas->Draw(0, 0, Picture1->Icon);

    delete Picture1;

    delete Icon1;

}


TBitmap::Empty example

The following loads a file into Graphic1 if it does not already contain a graphic.

void __fastcall TForm1::FormPaint(TObject *Sender)

{

  Graphics::TBitmap* Graphic1 = new Graphics::TBitmap();

  if(Graphic1->Empty)

    {

    	Graphic1->LoadFromFile("c:\\windows\\earth.bmp");

    }

  Form1->Canvas->Draw(0,0,Graphic1);

  delete Graphic1;

}


TBitmap::Monochrome example

The following code creates Bitmap1 and sets its Monochrome to True.

Note: Declare a "Graphics::TBitmap* Bitmap1" in header file.

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

Bitmap1 = new Graphics::TBitmap();

    Bitmap1->Monochrome = true;

    Bitmap1->LoadFromFile("c:\\windows\\earth.bmp");

}


TCanvas::Arc example

The following lines of code draw the top quarter of an arc

bounded by the current window.

void __fastcall TForm1::FormPaint(TObject *Sender)

{

TRect R = GetClientRect();	//Gets the rectangular 	//coordinates of the

    	//current window.

    	Canvas->Arc(R.Left, R.Top, R.Right, R.Bottom, R.Right, R.Top, 	R.Left, R.Top);

}


TCanvas::Chord example

This code draws a chord on the top of an ellipse bounded by the current window.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TRect R = GetClientRect();	//Gets the rectangular 	//coordinates of the

//current window.

    	Canvas->Chord(R.Left, R.Top, R.Right, R.Bottom,

    	R.Right, R.Top, R.Left, R.Top);

}


TCanvas::CopyMode example

The following code copies the inverted source bitmap to the canvas of the form.

TRect ClientRect;

//---------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

ClientRect.Left = Left;

    	ClientRect.Top = Top;

    	ClientRect.Right = Left + Width;

    	ClientRect.Bottom = Top - Height;

}

//---------------------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Canvas->CopyMode = cmNotSrcCopy;

    	Canvas->CopyRect(ClientRect, Canvas, ClientRect);

}


TCanvas::Draw example

The following code draws the graphic in C:\WINDOWS\TARTAN.BMP centered in Form1 when the user clicks Button1.  Attach this code to the OnClick event handler of Button1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Graphics::TBitmap* bitmap1 = new Graphics::TBitmap();

    	bitmap1->LoadFromFile("c:\\windows\\tartan.bmp");

    	Canvas->Draw((Width/2) - (bitmap1->Width/2),

    	 (Height/2) - (bitmap1->Height/2), bitmap1);

}


TCanvas::DrawFocusRect example

This example uses a radio button and a button on a form.  When the user clicks the button, the code draws a rectangle around the radio button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TRect R;

R = RadioButton1->BoundsRect;

    	R.Left = R.Left - 10;

    	R.Top = R.Top - 10;

    	R.Right = R.Right + 10;

    	R.Bottom = R.Bottom + 10;

Canvas->DrawFocusRect(R);

}


TCanvas::Ellipse example

The following code draws an ellipse filling the background of a form:

void __fastcall TForm1::FormPaint(TObject *Sender)

{

Canvas->Ellipse(0, 0, ClientWidth, ClientHeight);

}


TCanvas::FillRect example

This code creates a rectangle on the form's canvas and colors it red by changing the Canvas Brush property to clRed.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TRect NewRect = Rect(20, 30, 50, 90);

    	Canvas->Brush->Color = clRed;

    	Canvas->FillRect(NewRect);

}


TCanvas::FloodFill example

The following code floodfills from the center point of Form1's client area until the color black is encountered:

Canvas->FloodFill(ClientWidth/2, ClientHeight/2, clBlack, fsBorder);


TCanvas::FrameRect example

The following code displays the text "Hello world" in a rectangle defined by the coordinates (10, 10) and (100, 100).  After displaying the text with the TextRect method, the code draws a black, vertical line fram around the rectangle.

TRect TheRect;

    	Canvas->Brush->Color = clBlack;

    	Canvas->Brush->Style = bsVertical;

    	TheRect.Top = 10;

    	TheRect.Left = 10;

    	TheRect.Bottom = 100;

    	TheRect.Right = 100;

    	Canvas->TextRect(TheRect, 10, 10, "Hello World");

    	Canvas->FrameRect(TheRect);


TCanvas::LineTo example

The following code draws a line from the upper left corner of a form to the point clicked with the mouse.

void __fastcall TForm1::FormMouseDown(TObject *Sender, TMouseButton Button,

TShiftState Shift, int X, int Y)

{

Canvas->MoveTo(0, 0);

    	Canvas->LineTo(X, Y);

}


TCanvas::MoveTo example

The following code draws a line from the upper left corner of a form to the point clicked with the mouse.

void __fastcall TForm1::FormMouseDown(TObject *Sender, TMouseButton Button,

TShiftState Shift, int X, int Y)

{

Canvas->MoveTo(0, 0);

    	Canvas->LineTo(X, Y);

}


TCanvas::Pen example

The following code prints a rectange that uses a pen 40 pixels wide when the user clicks the button on the form.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Canvas->Pen->Width = 40;

Canvas->Rectangle(30, 30, 100, 100);

}


TCanvas::Pie example

This code draws a section of an ellipse on the form's Canvas when the user clicks the button on the form:

Canvas->Pie(10, 10, 200, 200, 61, 3, 200, 61);


TCanvas::Pixels example

The example draws a red line(very slowly) when the user presses the button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

for(int i = 10; i < 200; i++)

    	Canvas->Pixels[i][10] = clRed;

}


TCanvas::Rectangle example

This example draws many rectangles of various sizes and colors on a form maximized to fill the entire screen.  To run the code, drop a TTimer component on the form and use the object inspector to create the  OnTimer event.

int x, y;

//---------------------------------------------------------------------

void __fastcall TForm1::FormActivate(TObject *Sender)

{

WindowState = wsMaximized;

    	Canvas->Pen->Width = 5;

    	Canvas->Pen->Style = psDot;

Timer1->Interval = 50;

    	randomize();

}

//---------------------------------------------------------------------

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

x+= 4;

    	y+=4;

    	Canvas->Pen->Color = random(65535);

    	Canvas->Rectangle(x, y, x + random(400), y + random(400));

    	if(x > 700)

    	Timer1->Enabled = false;

}


TCanvas::RoundRect example

This example draws many rounded rectangles of various sizes and colors on a form maximized to fill the entire screen.  To run the code, drop a TTimer component on the form and use the object inspector to create the  OnTimer event.

int x, y;

//---------------------------------------------------------------------

void __fastcall TForm1::FormActivate(TObject *Sender)

{

WindowState = wsMaximized;

    	Canvas->Pen->Width = 5;

    	Canvas->Pen->Style = psDot;

Timer1->Interval = 50;

    	randomize();

}

//---------------------------------------------------------------------

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

x+= 4;

    	y+=4;

    	Canvas->Pen->Color = random(65535);

    	Canvas->RoundRect(x, y, x + random(400), y + random(400), 10, 10);

    	if(x > 700)

    	Timer1->Enabled = false;

}


TCanvas::StretchDraw example

The following code stretches the bitmap to fill the client area of Form1.

Canvas->StretchDraw(ClientRect, graphic);


TCanvas::TextHeight example

This example displays the height of a text string in the current font of the canvas in an edit box on the form:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

int x = Canvas->TextHeight("C++Builder is the best");

    	Edit1->Text = String(x) + String(" pixels in height");

}


TCanvas::TextOut example

This example displays a text string at a specified position on the form when the user clicks the button on the form:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Canvas->TextOut(20, 20, "C++Builder makes Windows programming easy");

}


TCanvas::TextRect example

The following code outputs the text "Hello World" in a rectangle defined by the coordinates (10, 10) and (100, 100).

void __fastcall TForm1::Button1Click(TObject *Sender)

{

TRect TheRect;

    	TheRect.Top = 10;

    	TheRect.Left = 10;

    	TheRect.Bottom = 100;

    	TheRect.Right = 100;

    	Canvas->TextRect(TheRect, 20, 20, String("Hello World"));

}


TCanvas::TextWidth example

This example determines the width of a specified string, and if the string is too wide to display in an edit box, the edit box is widened to accommodate the string.  The string displays in the edit box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

long int t;

    	String str("C++Builder is the best");

    	t = Canvas->TextWidth(str);

    	if(t > Edit1->Width)

    	Edit1->Width = t + 10;

    	Edit1->Text = str;

}


TClipboard::AsText example

The following code retrieves the contents of the Clipboard as a string and displays the value in a

label:

note: You will need to include <vcl\Clipbrd.hpp>.

void __fastcall TForm1::Label1Click(TObject *Sender)

{

Label1->Caption = Clipboard()->AsText;

}


TClipboard::FormatCount example

The following code adds each format on the Clipboard to ListBox1 when Button1 is clicked:

note: You will need to include <vcl\Clipbrd.hpp>.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

    for(int i=0; i < Clipboard()->FormatCount-1;i++)

    {

    	ListBox1->Items->Add(IntToStr(Clipboard()->Formats[i]));

    }

}


TControlScrollBar::Increment example

This example implements a horizontal scroll bar on the form. The scroll bar scrolls the form 100 pixels more than the form width. Each time the user clicks a scroll arrow on the scroll bar, the form scrolls 7 pixels:

__fastcall TForm1::TForm1(TComponent* Owner): TForm(Owner)

{

ClientWidth = 300;

    HorzScrollBar->Position = 0;

HorzScrollBar->Increment = 7;

    HorzScrollBar->Range = ClientWidth = 100; //Range must be greater than the

    	//form's client width..

    HorzScrollBar->Visible = true;

}


TControlScrollBar::Range example

This example uses a button on a form. When the user clicks the button, a vertical scroll bar alternately appears and disappears on the form, because the value of the Range property changes with each click.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

ClientHeight = 300;

    VertScrollBar->Visible = true;

    if(VertScrollBar->Range == 290)

    {

    	VertScrollBar->Range = 500;

    }

    else

    	VertScrollBar->Range = 290;

}


TControlScrollBar::ScrollPos example

This example uses a label on a form. When the application runs, resize the form so a horizontal scroll bar appears. You can use the scrollbar to scroll the form. Each time you click the lable, it reports the current position of the scroll bar:

void __fastcall TForm1::Label1Click(TObject *Sender)

{

Label1->Caption = "Scroll bar position is " + IntToStr(HorzScrollBar->ScrollPos);

}


TControlScrollBar::Tracking example

This example uses a ScrollBox on a form. When the user clicks the scroll box, a vertical scroll bar appears on the form. If Tracking is set to true, the image in the scroll box or form moves as the user drags the thumb tab. If Tracking is set to false, the image remains static until the thumb tab is released.

void __fastcall TForm1::ScrollBox1Click(TObject *Sender)

{

   	ClientHeight = 300;

    VertScrollBar->Tracking = false;

    if(VertScrollBar->Range == 290)

    {

    	VertScrollBar->Range = 500;

    }

    else

    	VertScrollBar->Range = 290;

}


TCustomLabel::FocusControl example

This code displays a line of text in a label on the form and associates the label with an edit box control. Note that the label caption includes an accelerator key. When the user presses ALT+N, the edit box control recieves the focus:

Label1->Caption = "&Name";

Label1->FocusControl = Edit1;

For this example, you need to place a label and a edit box control close together to make sure that users understand that they should enter text in the edit box.


TCustomOutline::Add example

The following code adds a new item at the top level of the outline. The new item is identified by the text "New Item":

Outline1->Add(0, "New Item");

This code adds a new item to the last sibling of the currently selected

item when the user pushes Button1:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

   Outline1->Add(Outline1->SelectedItem, "New sibling");

}


TCustomOutline::AddChild example

This code adds a new item as the last child of the currently selected item when the user pushes Button1:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

   Outline1->AddChild(Outline1->SelectedItem, "New child");

}


TCustomOutline::AddChildObject example

The following code adds a new child to the selected item of the outline. The new item is identified by the text "New child". The TBitmap object named Bitmap1 is attached to the new item:

Outline1->AddChildObject(Outline1->SelectedItem, "New child", Bitmap1);


TCustomOutline::AddObject example

The following code defines a structure type of TMyRec and a pointer type of PMyRec which points to the structure.

typedef struct MyRec

{

    AnsiString FName;

    AnsiString LName;

} TMyRec;

PMyRec = *TMyRec;

The following code adds an outline node to Outline1. A TMyRec record is associated with the added item. The FName and LName fields are obtained from edit boxes Edit1 and Edit2. The Index parameter is obtained from edit box Edit3. The item is added only if the Index is a valid value.

PMyRec   MyRecPtr;

long  OutlineIndex;

{

  new MyRecPtr;

  MyRecPtr->FName = Edit1->Text;

  MyRecPtr->LName = Edit2->Text;

  OutlineIndex = StrToInt(Edit3->Text);

  if ((OutlineIndex <= Outline1->ItemCount) && (OutlineIndex >= 0))

    Outline1->AddObject(OutlineIndex, "New item", MyRecPtr);

}

After an item containing a TMyRec record has been added, the following code retrieves the FName and LName values associated with the item and displays the values in labels.

Label1->Caption = PMyRec(Outline1->Items[Outline1->SelectedItem]->Data)->FName;

Label2->Caption = PMyRec(Outline1->Items[Outline1->SelectedItem]->Data)->LName;


TCustomOutline::ItemCount example

The following code turns off automatic reindexing before inserting a new item into the index if the index includes more than 100 items. Otherwise, automatic reindexing remains active.

Outline1->BeginUpdate();

Outline1->SetUpdateState(Outline1->ItemCount > 100);

Outline1->Insert(Outline1->SelectedItem, "NewItem");

Outline1->EndUpdate();


TCustomOutline::ItemHeight example

The following code sets the style of Outline1 to owner-draw and the height of each outline node to the height of 30 pixels:

Outline1->Style = otOwnerDraw;

Outline1->ItemHeight = 30;


TCustomOutline::Items example

The following code collapses the selected item of Outline1. The code does this using the Expanded property of TOutlineNode

Outline1->Items[Outline1->SelectedItem]->Expanded = false;


TCustomOutline::ItemSeparator example

The following code changes the item separator to "-|-“.

Outline1->ItemSeparator = "-|-";


TCustomOutline::Lines example

This line of code appends the node ChildZZ to the end of Outline1.

  Outline1->Lines->Add("ChildZZ");

To append children to an outline node, use the Items property.


TCustomOutline::OutlineStyle example

The following code displays pictures only if they are monochrome. The first choice is Open and Closed pictures. If they aren't monochrome, the code tests Plus and Minus pictures. The final resort is to simply display text.

  if (PictureOpen->Monochrome && PictureClosed->Monochrome)

    OutlineStyle = osPictureText;

  else if (PicturePlus->Monochrome && PictureMinus->Monochrome)

    OutlineStyle = osPlusMinusText;

  else

    OutlineStyle = osText;


TCustomOutline::PictureClosed example

The following code loads a new bitmap for the PictureClosed property of Outline1.

Outline1->PictureClosed->LoadFromFile("C:\closed.bmp");


TCustomOutline::PictureLeaf example

The following code tests the Width of the leaf picture. If it is wider than ten pixels, the OutlineStyle is changed so that the leaf picture is not displayed.

if (Outline1->PictureLeaf->Width > 10)

  Outline1.OutlineStyle = osTreeText;


TCustomOutline::PictureMinus example

The following code displays the same picture for the plus and minus states of Outline1. The same graphic appears whether an item is expanded or collapsed.

Outline1->PictureMinus = Outline1->PicturePlus;


TCustomOutline::PictureOpen example

The following code copies the text "Hello world" into the PictureOpen bitmap.

Outline1->PictureOpen->Canvas->TextOut(0, 0, "Hello world");


TCustomOutline::PicturePlus example

The following code allows the user to specify the graphic for the PicturePlus property of Outline1 using the Open dialog box.

if (OpenDialog1->Execute)

  Outline1->PicturePlus->LoadFromFile(OpenDialog1->FileName);


TCustomOutline::SelectedItem example

The following code collapses the selected item of Outline1. The code does this using the Expanded property of TOutlineNode:

Outline1->Items[Outline1->SelectedItem]->Expanded = false;


TCustomOutline::Style example

The following code sets the style of Outline1 to owner-draw and the height of each outline node to the height of 30 pixels:

Outline1->Style = otOwnerDraw;

Outline1->ItemHeight = 30;


TDatabase::AliasName example

Database1->AliasName = "BCDEMOS";


TDatabase::Close example

Database1->Close();


TDatabase::CloseDataSets example

Database1->CloseDataSets();


TDatabase::Commit example

    Database1->StartTransaction();

    //Update one or more records in tables linked to Database1

    Database1->Commit();


TDatabase::Connected example

Database1->Connected = true;


TDatabase::DatabaseName example

Database1->DatabaseName = "Builder_Demos";


TDatabase::DriverName example

Database1->DriverName = "STANDARD";


TDatabase::KeepConnection example

Database1->KeepConnection = false;


TDatabase::LoginPrompt example

The following example prohibits the display of the login prompt:

Database1->LoginPrompt = false;


TDatabase::Open example

Database1->Open();


TDatabase::Rollback example

Database1->StartTransaction();

//Update one or more records in tables linked to Database1

Database1->Rollback();


TDatabase::StartTransaction example

Database1->StartTransaction();

//Update one or more records in tables linked to Database1

Database1->Commit();


TDatabase::Temporary example

Database1->Temporary = false;


TDatabase::TransIsolation example

Database1->TransIsolation = tiReadCommitted;


TDataSet::Active example

This example will toggle the table's Active property and update the form's caption accordingly.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Table1->Active = !(Table1->Active);

  	if(Table1->Active)

    	Caption = "Table is Active";

  	else

    	Caption = "Table is not Active";

}


TDataSet::Last example

Table1->Last();


TDataSet::Locate example

The following code moves the cursor to the first row in the CustTable where the value in the Company column is "Professional Divers, Ltd.":

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  	TLocateOptions SearchOptions;

//Allow search for a partial key.

SearchOptions = SearchOptions<<loPartialKey;

    	//Test if we find the record

  	if(Table1->Locate("Company", "Professional Divers, Ltd.", SearchOptions))

    	ShowMessage("Found the Record");

   	 else

    	ShowMessage("Record not Found");

}

If Locate finds a match, the first record containing the match becomes the current record. Locate returns true if it finds a matching record, false if it does not. If a search fails, the current record does not change.


TDataSet::MoveBy example

The following code skips three records forward:

Table1->MoveBy(3);


TDataSet::State example

//Open the dataset if it is not already

if(Table1->State == dsInactive)

    	Table1->Active = true;


TDBText::DataField example

The following code specifies that the DataField of DBEdit1 is 'FNAME'.

DBEdit1->DataField = 'FNAME';


TDBText::DataSource example

The following code specifies DataSource1 to be the DataSource of DBGrid1.

DBGrid1->DataSource = DataSource1;


TDdeClientConv::CloseLink example

The following code terminates the DDE conversation.

DdeClientConv1->CloseLink();


TDdeClientConv::ConnectMode example

The following code sets the connect mode of DdeClientConv1 to manual.

DdeClientConv1->ConnectMode = ddeManual;


TDdeClientConv::DdeService example

The following code specifies a DDE service of "Project1".

DdeClientConv1->DdeService = String("Project1");


TDdeClientConv::DdeTopic example

The following code specifies a DdeTopic of "Form1".

DdeClientConv1->DdeTopic = "Form1";


TDdeClientConv::FormatChars example

The following code formats characters if the DdeService name is "SuperWrd".

if(DdeClientConv1->DdeService.AnsiCompare(String("SuperWrd") ))

    	DdeClientConv1->FormatChars = true;


TDdeClientConv::OpenLink example

The following code requests data if a link is open

if(DdeClientConv1->OpenLink())

    	DdeClientConv1->RequestData(DdeClientItem1->DdeItem);


TDdeClientConv::PokeData example

The following code pokes the data that is in Edit1 to the DDE server.  The DDE item of the conversation is specified in the DdeItem property of the DdeClientItem1.

DdeClientConv1->PokeData(DdeClientItem1->DdeItem, Edit1->Text.c_str());


TDdeClientConv::PokeDataLines example

The following code pokes the data that is in Edit1 to the DDE server.  The DDE item of the conversation is specified in the DdeItem property of the DdeClientItem1.

DdeClientConv1->PokeData(DdeClientItem1->DdeItem, Edit1->Text.c_str());


TDdeClientConv::ServiceApplication example

The following code sets the service application to "Test".

if(DdeClientConv1->DdeService.AnsiCompare(String("SuperWrd") ))

    	DdeClientConv1->FormatChars = true;


TDdeClientConv::SetLink example

The following code establishes a link with a DDE server.  The service is specified in the DdeService property of DdeClientConv1, and the topic is specified in the DdeTopic property of DdeclientConv1.  If the link is established, a message is displayed.

if(DdeClientConv1->SetLink(DdeClientConv1->DdeService, 	DdeClientConv1->DdeTopic) )

    	ShowMessage("Link Established");


TForm::ActiveControl example

The following event handler responds to timer events by moving the active control one pixel to the right:

void __fastcall TForm1::Timer1Timer(TObject *Sender)

{

ActiveControl->Left = ActiveControl->Left + 1;

}


TForm::ArrangeIcons example

This code runs when the user chooses a menu item called Window|Arrange Icons:

void __fastcall TForm1::ArrangeIcons1Click(TObject *Sender)

{

Form1->ArrangeIcons();

}


TForm::Canvas example

The following example paints a Rectangle on the form when the user clicks on Button1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Canvas->Rectangle(0, 0, 40, 40);

}


TForm::Cascade example

This code arranges all MDI children of the current MDI parent form in a cascade pattern when the user chooses the Cascade menu command:

void __fastcall TForm1::Cascade1Click(TObject *Sender)

{

Cascade();

}


TForm::Close example

The following method closes a form when a button called Done is clicked:

void __fastcall TForm1::DoneClick(TObject *Sender)

{

Close();

}


TForm::FormStyle example

This example ensures the main form of the application is an MDI parent form:

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

if(FormStyle != fsMDIForm)

    	FormStyle = fsMDIForm;

  	if(FormStyle == fsMDIForm)

    	Edit1->Text = "MDI form";

    	else

    	//This line never runs

    	Edit1->Text = "Not an MDI form";

}


TForm::GetFormImage example

This example uses an image, a button, and a shape component on a form. When the user clicks the button, an image of the form is stored in the FormImage variable and copied to the Clipboard. Then image of the form in then copied back to the image component, producing an interesting result, especially if the button is clicked multiple times.

Graphics::TBitmap *FormImage;

TClipboard *MyClip;

//------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

MyClip = new TClipboard();

}

//------------------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

FormImage = GetFormImage();

try

    	{

MyClip->Assign(FormImage);

    	Image1->Picture->Assign(MyClip);

    	}

    	catch(...)

    	{

        	delete FormImage;

}

}

//------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

Shape1->Shape = stEllipse;

  	Shape1->Brush->Color = clLime;

  	Image1->Stretch = true;

}

//------------------------------------------------------------------

void __fastcall TForm1::FormDestroy(TObject *Sender)

{

delete MyClip;

}


TForm::Icon example

This code assigns an icon to a form when the form is created:

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

Icon->LoadFromFile("C:\\PROGRAM FILES\\BORLAND\\CBUILDER\\IMAGES\\ICONS\\EARTH.ICO");

}


TForm::KeyPreview example

This example changes a form's color to aqua when the user presses a key, even when a control on the form has the focus. When the user releases the key, the form returns to its original color.

TForm1 *Form1;

TColor FormColor;

//------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

KeyPreview = true;

}

//------------------------------------------------------

void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key,

TShiftState Shift)

{

FormColor = Form1->Color;

  	Form1->Color = clAqua;

}

//------------------------------------------------------

void __fastcall TForm1::FormKeyUp(TObject *Sender, WORD &Key, TShiftState Shift)

{

Form1->Color = FormColor;

}


TForm::MDIChildCount example

The following code closes Form1 if there are no MDI children open:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if(MDIChildCount == 0)

    	Close();

}


TForm::MDIChildren example

The following code closes all the MDI children of Form1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

for(int i = 0; i < MDIChildCount; i++)

    	MDIChildren[i]->Close();

}


TForm::Menu example

This code displays a new menu named MyMenu when the user clicks the button.

TMenuItem *Item1;

TMainMenu *MyMenu;

//------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Item1=new TMenuItem(this);

  	Item1->Caption = "New item";

MyMenu = new TMainMenu(this);

    	MyMenu->Items->Add(Item1);

Menu = MyMenu;

}

//------------------------------------------------------

void __fastcall TForm1::FormDestroy(TObject *Sender)

{

for(int i = 0; i < MyMenu->Items->Count; i++)

    	MyMenu->Items[i].Remove(Item1);

delete Item1;

    	delete MyMenu;

}


TForm::Next example

The following code activates the next child of Form1.

Form1->Next();


TForm::OnActivate example

The following code adds the caption of Form2 to a list box in Form1 when a Form2 is activated.

#include "Unit1.h"	//so we can refer to Form1.

void __fastcall TForm2::FormActivate(TObject *Sender)

{

Form1->ListBox1->Items->Add(Screen->ActiveForm->Caption);

}


TForm::OnClose example

This example displays a message dialog box when the user attempts to close the form. If the user clicks the Yes button, the form closes; otherwise, the form remains open.

void __fastcall TForm1::FormClose(TObject *Sender, TCloseAction &Action)

{

if(Application->MessageBox("Close application ?", "Close?", MB_YESNO) == mrYes)

    	Action = caFree;

  	else

    	Action = caNone;

}


TForm::OnCloseQuery example

When the user attempts to close the form in this example, a message dialog appears that asks the user if it is OK to close the form. If the user chooses the Yes button, the form closes. If the user chooses Cancel or No, the form doesn't close.

void __fastcall TForm1::FormCloseQuery(TObject *Sender, bool &CanClose)

{

  	if(Application->MessageBox("Close the form?", "Close?",

    	MB_YESNOCANCEL) != mrYes)

CanClose = false;

}


TForm::OnCreate example

This very simple OnCreate event handler assures that the form is the same color as the Windows system color of your application workspace:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

Color = clAppWorkSpace;

}

Note:	The Color property in this example is not prefaced with the name of the form. If you write the statement like this,

Form1->Color = clAppWorkSpace;

the application won't run without error, because Form1 does not yet exist at the time this code is executed


TForm::OnDestroy example

The following code dynamically creates a button called BtnMyButton with the Caption "My Button".  The memory associated with the button is deleted when the form is destroyed.

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

BtnMyButton = new TButton(this);

BtnMyButton->Parent = this;

BtnMyButton->Caption = "My Button";

}

//------------------------------------------------------------------

void __fastcall TForm1::FormDestroy(TObject *Sender)

{

delete BtnMyButton;

}


TForm::OnHide example

This example uses two forms, each with a label and a button. When the user clicks a button, the other form appears and the current form disappears. Also, a message appears in the label of the form that is showing, indicating that the other form is hidden. This is the implementation section of Unit1:

#include "Unit2.h"

//------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//------------------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Form2->Show();

  	Hide();

}

//------------------------------------------------------------------

void __fastcall TForm1::FormHide(TObject *Sender)

{

Form2->Label1->Caption = "Form1 is hiding";

}

This is the implementation section of Unit2:

#include "Unit1.h"

//------------------------------------------------------------------

#pragma resource "*.dfm"

TForm2 *Form2;

//------------------------------------------------------------------

__fastcall TForm2::TForm2(TComponent* Owner)

: TForm(Owner)

{

}

//------------------------------------------------------------------

void __fastcall TForm2::Button1Click(TObject *Sender)

{

Form1->Show();

  	Hide();

}

//------------------------------------------------------------------

void __fastcall TForm2::FormHide(TObject *Sender)

{

Form1->Label1->Caption = "Form2 is hiding";

}


TForm::OnPaint example

The following code is loads a background bitmap onto the Canvas of the main form in the OnPaint event handler.

Graphics::TBitmap *TheGraphic;

//------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//------------------------------------------------------------------

void __fastcall TForm1::FormPaint(TObject *Sender)

{

//Draw the graphic on the Canvas

Form1->Canvas->Draw(0, 0, TheGraphic);

}

//------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

TheGraphic = new Graphics::TBitmap(); // Create the bitmap 	//object

    //Load the bitmap

  	TheGraphic->LoadFromFile("C:\\PROGRAM FILES\\BORLAND\\CBUILDER\\IMAGES\\BACKGRND\\CALENDAR.BMP");

}


TForm::OnResize example

The following code keeps the right edge on Button1 against the right edge of Form1 when Form1 is resized.

void __fastcall TForm1::FormResize(TObject *Sender)

{

Button1->Left = Form1->ClientWidth - Button1->Width;

}


TForm::OnShow example

This example colors the form and changes its caption when it becomes visible:

void __fastcall TForm1::FormShow(TObject *Sender)

{

Color = clLime;

  	Caption = "I am showing";

}


TForm::Previous example

This code sample activates the previous child window of the parent (Form1) when the user selects a menu item named Previous on a menu.

void __fastcall TForm1::PreviousClick(TObject *Sender)

{

Previous();

}


TForm::Print example

This example uses a button named Print on a form. When the user chooses the button, the form prints.

void __fastcall TForm1::PrintClick(TObject *Sender)

{

Print();

}


TForm::PrintScale example

The following code maintains the proportions of the form when it is printed.

Form1->PrintScale = poProportional;

Form1->Print();


TForm::Release example

This example displays a message box about the form going away, calls Release, and terminates the application.

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Application->MessageBox("This form is going away forever", "Release Notice", MB_OK);

  	Release();

  	Application->Terminate();

}


TForm::ShowModal example

The following code displays a message box after OKBottomDlg is shown modally and is closed by an OK button.

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

OKBottomDlg->ShowModal();

if(OKBottomDlg->ModalResult == mrOk)

  	Application->MessageBox("OK!", "Modal", MB_OK);

}

This code uses two forms and a button on the first form. The user must close Form3 before the focus returns to Form1.

#include "Unit3.h"

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Form3->ShowModal();

}


TForm::Tile example

This example uses three forms. The first form has its FormStyle property set to MDIForm. The other two have their FormStyle properties set to MDIChild and their Visible properties set to True. Add a main menu component and name one of the menu items TileForms. This is code for the TileFormsClick handler:

void __fastcall TForm1::TileFormsClick(TObject *Sender)

{

TileMode = tbVertical;

Tile();

}

When the user chooses the TileForms command, the child forms tile vertically within the MDI frame form.


TForm::TileMode example

This example uses three forms. The first form has its FormStyle property set to MDIForm. The other two have their FormStyle properties set to MDIChild and their Visible properties set to true. Add a main menu component and name one of the menu items TileForms. This is code for the TileForms1Click handler:

void __fastcall TForm1::TileForms1Click(TObject *Sender)

{

TileMode = tbHorizontal;

  	Tile();

}

When the application runs and the user chooses the TileForms command, the child forms tile horizontally within the MDI frame form.


TForm::WindowMenu example

For this code to run, a menu item called MyWindows must exist on an MDI form parent form. This line of code designates the MyWindows menu to be the Window menu, the menu that lists all open child windows in an MDI application:

WindowMenu = MyWindows;


TForm::WindowState example

The following code responds to the user clicking a button named Shrink by minimizing the form:

void __fastcall TForm1::ShrinkClick(TObject *Sender)

{

WindowState = wsMinimized;

}


TGraphic::Empty example

The following loads a file into Graphic1 if it does not already contain a graphic.

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

  Graphics::TBitmap* Graphic1 = new Graphics::TBitmap();

  if(Graphic1->Empty)

    {

    	Graphic1->LoadFromFile("earth.bmp");

    }

  Form1->Canvas->Draw(0,0,Graphic1);

  delete Graphic1;

}


TImage::AutoSize example

This example uses an image control and a button. Resize the image control so that it is too small to display the entire bitmap. When the user clicks the button, the bitmap is loaded into the image control, and the image control resizes to display the bitmap in its entirety.

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Imagel->AutoSize  = true;

Imagel->Picture->LoadFromFile("c:\\windows\\abitmap.bmp");

}


TImage::Canvas example

The following example paints a cross-hatched ellipse Image1 which is a TImage on the form when the user clicks on Button1.

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Image->Canvas->Brush->Color = clBlack;

Image->Canvas->Brush->Style = bsDiagCross;

Image->Canvas->Ellipse(0, 0, Image1->Width, Image1->Height);

}


TImage::Pictures example

This example uses two picture components. When the form first appears, two bitmaps are loaded into the picture components and stretched to fit the size of the components. To try this code, substitute names of bitmaps you have available.

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Image1->Stretch = true;

Image2->Stretch = true;

Image1->Picture->LoadFromFile("c: \\windows\\earth.bmp");

Image2->Picture->LoadFromFile("c: \\windows\\Plus!.bmp");

}


TMetafile::Empty example

The following loads a file into Graphic1 if it does not already contain a graphic.

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

  Graphics::TBitmap* Graphic1 = new Graphics::TBitmap();

  if(Graphic1->Empty)

    {

    	Graphic1->LoadFromFile("earth.bmp");

    }

  Form1->Canvas->Draw(0,0,Graphic1);

  delete Graphic1;

}


TPrinter::Abort example

The following code aborts a print-job if the user presses Esc. Note thet you should set KeyPreview to true to ensure that the OnKeyDown event handler is called.

void __fastcall TForm1::FormKeyDown(TObject *Sender, WORD &Key,

TShiftState Shift)

{

   if ((Key == VK_ESCAPE) &&(Printer()->Printing)) {

      Printer()->Abort();

      MessageBox(0, "Printing aborted.", "Info", MB_OK);

   }

}


TPrinter::Aborted example

The following code displays a message box if the print job was aborted:

if (Printer->Aborted)

  Application->MessageBox("The print job did not finish printing.", "Alert!", MB_OK);


TPrinter::BeginDoc example

This code prints a rectangle on the default printer:

Printer()->BeginDoc()                              // begin to send print job to printer

  Printer()->Canvas->Rectangle(20,20,1000,1000);     // draw rectangle on printer's canvas

  Printer()->EndDoc;                          // EndDoc ends and starts printing print job


TPrinter::Canvas example

The following code prints the text "Hello, world!"

Printer()->BeginDoc();

Printer()->Canvas()->TextOut(0, 0, "Hello, world");

Pritner()->EndDoc;


TPrinter::EndDoc example

This code prints a rectangle on the default printer:

Printer()->BeginDoc()                              // begin to send print job to printer

  Printer()->Canvas->Rectangle(20,20,1000,1000);     // draw rectangle on printer's canvas

  Printer()->EndDoc;                          // EndDoc ends and starts printing print job


TPrinter::Fonts example

This code displays the fonts supported by the screen in a FontList list box when the user clicks the ListFonts button:

void __fatscall TForm1::ListFontsClick(TObject* Sender)

{

  FontList->Clear();

  FontList->Sorted = true;

  FontList->Items = Screen->Fonts;

}


TPrinter::NewPage example

This example uses a button on a form. When the user clicks the button, a rectangle is printed twice, one per page.

void __fastcall TForm1::Button1Click(TObject* Sender)

{

  Printer()->BeginDoc();

  Printer()->Canvas->Rectangle(10, 10, 200, 200);

  Printer()->NewPage();

  Printer()->Canvas->Rectangle(10, 10, 200, 200);

  Printer()->EndDoc();

}


TPrinter::Orientation example

This example uses two radio buttons on a form named Landscape and Portrait. The form also includes a button. When the user selects an orientation by clicking one of the radio buttons and then clicks the button to print one line of text, the print job prints using the selected orientation:

void __fastcall TForm1::Button1Click(TObject Sender*)

{

  Printer()->BeginDoc();

  Printer()->Canvas->TextOut(100,100,"Hi there!");

  Printer()->EndDoc();

}

//---------------------------------------------------------------

void __fastcall TForm1::PortraitClick(TObject* Sender)

{

  Printer()->Orientation = poPortrait;

}

//---------------------------------------------------------------

void __fastcall TForm1::LandscapeClick(TObject* Sender)

{

  Printer()->Orientation = poLandscape;

}

//---------------------------------------------------------------


TPrinter::PageHeight example

This code displays the page height of the currently printing page in an edit box.

To run this code successfully, you must #include <Printers.hpp> to your unit.

Edit1->Text = Printer()->PageHeight;


TPrinter::PageNumber example

This example uses a button on a form. When the user clicks the button, one line of text is printed on six separate pages. As each page is printed, a message indicating the number of the page being printed appears on the form.

To run this example successfully, you #include <Printers.h> to your unit.

void __fsatcall TForm1::Button1Click(TObject Sender*)

{

  int i,

      x,

      y;

  Printer()->BeginDoc();

  x = 10;

  y = 10;

  for (i = 1;i < 7;i++) {

      Printer()->Canvas->TextOut(100, 100, "C++Builder rules!");

      Canvas->TextOut(x, y, AnsiString("Printing page ") + Printer()->PageNumber);

      Printer()->NewPage();

      y += 20;

  }

  Printer()->EndDoc();

}


TPrinter::PageWidth example

The code uses an edit box on a form. The code displays the current width of a page in pixels in the edit box when the form first appears.

void __fastcall TForm1::FormCreate(TObject* Sender)

{

  Edit1->Text = AnsiString(Printer()->PageWidth) + " pixels.";

}


TPrinter::PrinterIndex example

The following code asks the user if they want to use the default printer. If they choose yes, PrinterIndex specifies the default printer. The code assumes that Printer1 is a TPrinter object.

if (MessageBox(0, "Do you want to use the default printer?",

    "Question.", MB_YESNOCANCEL | MB_ICONQUESTION) == IDYES)

      Printer1->PrinterIndex = -1;


TPrinter::Printers example

The following code displays the names of all printers in ListBox1.

{

  ListBox1->Items = Printer()->Printers;

}


TPrinter::Printing example

This code indicates if there is a print job on the current printer:

if (Printer()->Printing)

  MessageBox(0, "Print job on current printer.", "Info", MB_OK);


TPrinter::Title example

This line of code sets the value of the Title property for the printer object:

Printer()->Title = "My incredible application.";


TQuery::DataSource example

This example illustrates the use of the DataSource property to link a query in a master-detail form.  The form contains a TQuery component named Query1 with the following in its SQL propery:

SELECT Orders.CustNo, Orders.OrderNo, Orders.SaleDate

   FROM Orders

   WHERE Orders.CustNo = :CustNo

The form also contains:

A TDataSource named DataSource1, linked to Query1 by its DataSet property.

A TTable component named Table1

A TDataSource named DataSource2 linked to Table1.

Two data grids; one linked to DataSource1 and one linked to DataSource2.

Each time the Table1 moves to a different row, the Query1 query automatically re-executes to retrieve all the orders for the current customer.


TQuery::ExecSQL example

Query1->Close();

Query1->SQL->Clear();

Query1->SQL->Add("Delete from Country where Name = 'Argentina'");

Query1->ExecSQL();


TQuery::Local example

//If the table is local, allow the data-aware 	//controls to display the changes

DataSource1->Enabled = Query1->Local;


TQuery::Prepared example

if(!Query1->Prepared)

    	{

Query1->Close();

  	Query1->Prepared = true;

    	}


TShape::Pen example

The following code prints a rectangle that uses a pen 40 pixels wide when the user clicks the button on the form:

void __fastcall TForm1::ButtonClick(TObject *Sender)

{

Printer->Canvas->Pen->Width = 40;

Printer->BeginDoc;

Printer->Canvas->Rectangle(30, 30, 400, 600);

Printer->EndDoc;

}


TShape::Shape example

This example uses a shape component on a form. When the user clicks the shape, it becomes a ball with red stripes:

void __fastcall TForm1::Shape1MouseDown(TObject *Sender, TmouseButton *Button, TshiftState *Shift, int X, int Y)

{

Shape1->Shape = stCircle;

Shape1->Color = clRed;

Shape1->Style = bsVertical;

}


TSpeedButton::Down example

This code displays the speed button in a down state:

SpeedButton1->Down = true;


TStoredProc::CopyParams example

The following code copies all parameters from StoredProc1 to StoredProc2:

StoredProc1->CopyParams(StoredProc2->Params);


TStoredProc::ExecProc example

The following code executes the stored procedure:

StoredProc1->Params->Items[0]->AsString = Edit1->Text;

StoredProc1->Prepare();

StoredProc1->ExecProc();


TStoredProc::ParamBindMode example

StoredProc1->ParamBindMode = pbByName;


TStoredProc::ParamByName example

StoredProc1->Open();

while(!StoredProc1->Eof)

{

  	StoredProc1->Next();

  	//Do Something

}

StoredProc1->GetResults();

    	Edit1->Text = StoredProc1->ParamByName("Output")->AsString;


TStoredProc::ParamCount example

//Set all parameters to an empty string

for(int i = 0; i < StoredProc1->ParamCount; i++)

    	StoredProc1->Params->Items[i]->AsString = "";


TStoredProc::Params example

//Copy all parameters from StoredProc1 to StoredProc2

StoredProc1->CopyParams(StoredProc2->Params);


TStoredProc::Prepare example

StoredProc1->Params->Items[0]->AsString = Edit1->Text;

StoredProc1->Prepare();

StoredProc1->ExecProc();


TStoredProc::Prepared example

//Make sure that the server is aware that we will be executing the procedure

  	if(!StoredProc1->Prepared)

    	StoredProc1->Prepared = true;


TStoredProc::StoredProcName example

StoredProc1->StoredProcName = "foo";


TStoredProc::Unprepare example

StoredProc1->UnPrepare();


TStringGrid::CellRect example

This example uses a string grid, four labels, and a button on a form. When the user clicks the button, the coordinates of the cell in the second column and first row appear in the label captions.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TRect Rectangle = StringGrid1->CellRect(3, 2);

  Label1->Caption = AnsiString(Rectangle.Top) + " is the top";

  Label2->Caption = AnsiString(Rectangle.Bottom) + " is the bottom";

  Label3->Caption = AnsiString(Rectangle.Left) + " is the left side";

  Label4->Caption = AnsiString(Rectangle.Right) + " is the right side";

}


TStringGrid::MouseToCell example

This example uses a string grid on a form. When the user selects a cell in the grid and releases the mouse button, the column and row coordinates for the cell appear in the cell. The code for displaying the coordinates is written in the OnMouseUp event handler:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  StringGrid1->DefaultColWidth = 100;

}

//---------------------------------------------------------------------------

void __fastcall TForm1::StringGrid1MouseUp(TObject *Sender, TMouseButton Button,

        TShiftState Shift, int X, int Y)

{

  long Column, Row;

  StringGrid1->MouseToCell(X, Y, Column, Row);

  StringGrid1->Cells[Column][Row] = "Col " + AnsiString((int)Column) +

                                    ",Row " + AnsiString((int) Row);

}


TStringList::Add example

BeginUpdate and EndUpdate should always be used in conjunction with a try...catch statement to ensure that EndUpdate is called if an exception occurs. A block that uses BeginUpdate and EndUpdate typically looks like this:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->BeginUpdate();

  try{

    ListBox1->Items->Clear();

    ListBox1->Items->Add("Some foo");

    ListBox1->Items->Add("Some data");

    ListBox1->Items->EndUpdate();

  }

  catch(...){

    ListBox1->Items->EndUpdate();  //Executed even in case of an exception

    throw;

  }

}


TStringList::Delete example

This example uses a list box and a button on a form. When the form appears, five items are in the list box. When the user clicks the button, the second item in the list box is deleted:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Delete(1);

}


TStringList::Exchange example

This example uses a list box that contains several strings as the value of the Items property, and a button. When the user clicks the button, the second and third items in the list box switch places in the list box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

     ListBox1->Items->Exchange(1, 2);

}


TStringList::Find example

This example uses a list box and a label on a form. When the application runs, a string list object is created and three strings are added to it. The Find method searches the strings to look for a match with the string 'Flowers'. If the string is found, all the strings in the string list are added to the list box, and the index value of the 'Flowers' string appears in the caption of the label control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int Index;

  TStringList* MyList = new TStringList();

  MyList->Add("Animals");

  MyList->Add("Flowers");

  MyList->Add("Ocean");

  MyList->Sort();

  if (MyList->Find("Flowers", Index)){

    ListBox1->Items->AddStrings(MyList);

    Label1->Caption = "Flowers has an index value of " + AnsiString(Index);

  }

  delete MyList;

}


TStringList::IndexOf example

This example uses a file list box, a directory list box, and a label on a form. When the user uses the directory list box to change directories, a message appears and the color of the form changes if the file AUTOEXEC.BAT is in the new directory. The code is written in the OnChange event of the directory list box:

void __fastcall TForm1::DirectoryListBox1Change(TObject *Sender)

{

  FileListBox1->Directory = DirectoryListBox1->Directory;

  if (FileListBox1->Items->IndexOf("AUTOEXEC.BAT") > -1) {

    Color = clYellow;

    Label1->Caption = "You are in the root directory!";

  }

}


TStringList::Insert example

This example uses a list box and a button on a form. When the form appears, it contains five items. When the user clicks the button, another string is inserted at the top of the list of items:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Insert(0, "Inserted here");

}

//---------------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

   for (int i = 1; i <= 5; i++)

     ListBox1->Items->Add("Item " + AnsiString(i));

}


TStringList::Sort example

This example uses a list box and a label on a form. When the application runs, a string list object is created and three strings are added to it. The Find method searches the strings to look for a match with the string 'Flowers'. If the string is found, all the strings in the string list are added to the list box, and the index value of the 'Flowers' string appears in the caption of the label control.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int Index;

  TStringList* MyList = new TStringList();

  MyList->Add("Animals");

  MyList->Add("Flowers");

  MyList->Add("Ocean");

  MyList->Sort();

  if (MyList->Find("Flowers", Index)){

    ListBox1->Items->AddStrings(MyList);

    Label1->Caption = "Flowers has an index value of " + AnsiString(Index);

  }

  delete MyList;

}


TStrings::Add example

BeginUpdate and EndUpdate should always be used in conjunction with a try...catch statement to ensure that EndUpdate is called if an exception occurs. A block that uses BeginUpdate and EndUpdate typically looks like this:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->BeginUpdate();

  try{

    ListBox1->Items->Clear();

    ListBox1->Items->Add("Some foo");

    ListBox1->Items->Add("Some data");

    ListBox1->Items->EndUpdate();

  }

  catch(...){

    ListBox1->Items->EndUpdate();  //Executed even in case of an exception

    throw;

  }

}


TStrings::AddObject example

This code adds the string 'Orange' and a bitmap of an orange to an owner-draw list box:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TIcon* Icon;

  Icon = new TIcon;

  Icon->LoadFromFile("ORANGE.ICO");

  ListBox1->Items->AddObject("Orange", Icon);

}


TStrings::AddStrings example

This code adds the list of strings contained in ListBox1->Items to the end of the ListBox2->Items list of strings:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox2->Items->AddStrings(ListBox1->Items);

}


TStrings::Append example

This code uses a button and a list box on a form. When the user clicks the button, the code appends a new string to a list box.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Append("New String");

}


TStrings::Assign example

This example consists of a form with a memo and listbox.  When the button is clicked, the contents of the memo are filled with the contents of the listbox.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

   Memo1->Lines->Assign(ListBox1->Items);

}


TStrings::BeginUpdate example

BeginUpdate and EndUpdate should always be used in conjunction with a try...catch statement to ensure that EndUpdate is called if an exception occurs. A block that uses BeginUpdate and EndUpdate typically looks like this:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->BeginUpdate();

  try{

    ListBox1->Items->Clear();

    ListBox1->Items->Add("Some foo");

    ListBox1->Items->Add("Some data");

    ListBox1->Items->EndUpdate();

  }

  catch(...){

    ListBox1->Items->EndUpdate();  //Executed even in case of an exception

    throw;

  }

}


TStrings::Delete example

This example uses a list box and a button on a form. When the form appears, five items are in the list box. When the user clicks the button, the second item in the list box is deleted:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Delete(1);

}


TStrings::EndUpdate example

BeginUpdate and EndUpdate should always be used in conjunction with a try...catch statement to ensure that EndUpdate is called if an exception occurs. A block that uses BeginUpdate and EndUpdate typically looks like this:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->BeginUpdate();

  try{

    ListBox1->Items->Clear();

    ListBox1->Items->Add("Some foo");

    ListBox1->Items->Add("Some data");

    ListBox1->Items->EndUpdate();

  }

  catch(...){

    ListBox1->Items->EndUpdate();  //Executed even in case of an exception

    throw;

  }

}


TStrings::IndexOf example

This example uses a file list box, a directory list box, and a label on a form. When the user uses the directory list box to change directories, a message appears and the color of the form changes if the file AUTOEXEC.BAT is in the new directory. The code is written in the OnChange event of the directory list box:

void __fastcall TForm1::DirectoryListBox1Change(TObject *Sender)

{

  FileListBox1->Directory = DirectoryListBox1->Directory;

  if (FileListBox1->Items->IndexOf("AUTOEXEC.BAT") > -1) {

    Color = clYellow;

    Label1->Caption = "You are in the root directory!";

  }

}


TStrings::IndexOfName example

The following example merges the strings in the memo control into strings contained in the list box. If a string in the memo is of the form Name=Value and the Name is also contained in the list box, its value will be replaced by the list box's value.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  int P,DI;

  AnsiString S;

  for (int i = 0; i <= ListBox1->Items->Count - 1; i++){

    S = ListBox1->Items->Strings[i];

    P = S.Pos("=");

    if (P > 1){

      DI = Memo1->Lines->IndexOfName(AnsiString(S.SubString(1, P - 1)));

      if (DI > -1)

        Memo1->Lines->Strings[DI] = S;

    }

  }

}

//---------------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

   for (int i = 1; i <= 10; i++)

     ListBox1->Items->Add("Item " + AnsiString(i) + " = " + 100*i);

   for (int i = 5; i <= 15; i++)

     Memo1->Lines->Add("Item " + AnsiString(i) + " = " + 50*i);

}


TStrings::IndexOfObject example

The following code determines if MyObject is the first object in MyStringList.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  if (ListBox1->Items->IndexOfObject(MyObject) == 0)

    ShowMessage("foo");

}


TStrings::Insert example

This example uses a list box and a button on a form. When the form appears, it contains five items. When the user clicks the button, another string is inserted at the top of the list of items:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Insert(0, "Inserted here");

}

//---------------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

   for (int i = 1; i <= 5; i++)

     ListBox1->Items->Add("Item " + AnsiString(i));

}


TStrings::InsertObject example

The following code inserts the components of Form1 into the first position of the Lines list of Memo1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for (int i = 0; i < Form1->ComponentCount-1; i++)

    Memo1->Lines->InsertObject(0, Form1->Components[i]->Name, this);

}


TStrings::LoadFromFile example

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Memo1->Lines->LoadFromFile("Unit1.cpp");

}


TStrings::LoadFromStream example

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file and then saved to a new file.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Memo1->Lines->LoadFromStream(&TFileStream("Unit1.cpp", fmOpenRead));

  Memo1->Lines->SaveToStream(&TFileStream("Unit2.cpp", fmOpenWrite));

}


TStrings::Move example

This example uses a list box and a button on a form. The list box contains items when the form appears. When the user clicks the button, the fifth item in the list box is moved to the top of the list box:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  ListBox1->Items->Move(4,0);

}

//---------------------------------------------------------------------------

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  for (int i = 0; i < 10; i++)

    ListBox1->Items->Append("New String" + AnsiString(i));

}


TStrings::SaveToFile example

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file and then saved to a new file.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Memo1->Lines->LoadFromFile("Unit1.cpp");

  Memo1->Lines->SaveToFile("Unit2.cpp");

}


TStrings::SaveToStream example

This example uses a memo and a button on a form. When the button is clicked the memo is filled with the contents of the file and then saved to a new file.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  Memo1->Lines->LoadFromStream(&TFileStream("Unit1.cpp", fmOpenRead));

  Memo1->Lines->SaveToStream(&TFileStream("Unit2.cpp", fmOpenWrite));

}


TTable::Exclusive example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

//Try to open Table1 with Exclusive true

// First, close Table1

Table1->Active = false;

    	while(1)

    	{

    	//until successful or Cancel button is pressed }

  	try

    	{

    	Table1->Exclusive = true; // See if it will open

    	Table1->Active = true;

    	break; //if no error, exit the loop

    	}

  	catch(EDatabaseError& E)

        	{

        	//Ask if it is OK to retry

            	if(Application->MessageBox("Could not open Table1 exclusively - OK to retry?",

            	   "Error", MB_OKCANCEL) != ID_OK)

            	throw; //If not, throw to abort

      	//Otherwise resume the repeat loop

        	}

    	}

}


TTable::FindKey example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

if(Table1->FindKey(&TVarRec(1551), 0))

    	ShowMessage("Customer Found");

}


TTable::FindNearest example

When the user clicks a button, this example will search for CustNo >= 1551.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Table1->FindNearest(&TVarRec(1551), 0);

}


TTable::IndexDefs example

For this example, you will need a TDataSource, a TTable, and a TButton.  When the user clicks the button, an index is added and it then determines if the index field added is present in the IndexDefs property that contains information about the indexes for the table.

Note:  This example should be run from outside of the IDE without Borland C++Builder running.  Otherwise, a "Table is Busy" error message may result.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

//set the table to be inactive so that we can have exclusive access

Table1->Active = false;

    	Table1->Exclusive = true;

    	//Add an index so we can verify that it has been found

Table1->AddIndex(String("MyIndex"), String("CustNo;Company"), Options);

//Get the current available indices

Table1->IndexDefs->Update();

//Find one which combines Customer Number "CustNo" and "Company"

for(int i = 0; i < Table1->IndexDefs->Count; i++)

    	if(Table1->IndexDefs->Items[i]->Fields == 	String("CustNo;Company"))

        	ShowMessage("Found the index");

//Reopen the table.

    	Table1->Exclusive = false;

    	Table1->Active = true;

}


TTable::IndexName example

Table1->IndexName = String("CustNoIndex");


TTable::KeyExclusive example

This example limits the range of the index of the first field from 1351 to 1356 when the user presses the Button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

//Limit the range from 1351 to 1356, excluding both 1351 and 1356

//Set the beginning key

Table1->EditRangeStart();

  	Table1->IndexFields[0]->AsString = String("1351");

//Exclude 1351 itself

Table1->KeyExclusive = true;

//Set the ending key

  	Table1->EditRangeEnd();

  	Table1->IndexFields[0]->AsString = String("1356");

//Exclude 1356 itself

  	Table1->KeyExclusive = true;

//Tell the dataset to establish the range

  	Table1->ApplyRange();

}


TTable::MasterFields example

Suppose you have a master table named Customer that contains a CustNo field, and you also have a detail table named Orders that also has a CustNo field. To display only those records in Orders that have the same CustNo value as the current record in Customer, write this code:

Orders->MasterSource = CustSource;

Orders->MasterFields = String("CustNo");

If you want to display only the records in the detail table that match more than one field value in the master table, specify each field and separate them with a semicolon.

Orders->MasterFields = String("CustNo;SaleDate");


TTable::MasterSource example

Suppose you have a master table named Customer that contains a CustNo field, and you also have a detail table named Orders that also has a CustNo field. To display only those records in Orders that have the same CustNo value as the current record in Customer, write this code:

Orders->MasterSource = CustSource;

Orders->MasterFields = String("CustNo");

If you want to display only the records in the detail table that match more than one field value in the master table, specify each field and separate them with a semicolon.

Orders->MasterFields = String("CustNo;SaleDate");


TTable::ReadOnly example

Table1->Active = false;

    	Table1->ReadOnly = true;

    	Table1->Active = true;


TStoredProc::DescriptionsAvailable example

if(!StoredProc1->DescriptionsAvailable())

{

//Build the Params property

//explicitly

}


TClipboard::Formats example

The following code adds each format on the Clipboard to ListBox1 when Button1 is clicked:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

    for(int i=0; i < Clipboard()->FormatCount-1;i++)

    {

    	ListBox1->Items->Add(IntToStr(Clipboard()->Formats[i]));

    }

}


TApplication::Minimize example

This example uses a button named Shrink on a form. When the user clicks the button, the application minimizes to an icon:

void __fastcall TForm1::ShrinkClick(TObject* Sender)

{

  Application->Minimize();

}


TGraphicControl::Canvas example

The following example paints a cross-hatched ellipse onto Image1 which is a TImage on the form when the user clicks on Button1.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Image1->Canvas->Brush->Color = clBlack;

Image1->Canvas->Brush->Style = bsDiagCross;

Image1->Canvas->Ellipse(0, 0, Image1->Width, Image1->Height);

}


TDBDataSet::DatabaseName example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

EDatabaseError* e = new EDatabaseError("Database name failed");

//Close the DBDataSet

    	Table1->Active = false;

    	try

    	{

    	//first try to use an alias

        	Table1->DatabaseName = "BCBDemos";

        	Table1->Active = true;

    	}

    	catch(EDatabaseError *e)

    	{

    	//if that files try to use the drive and directory

        	Table1->DatabaseName = "c:\\program files\\borland\\cbuilder\\examples\\data";

        Table1->Active = true;

    	}

}


TDBDataSet::DBHandle example

This example uses the DBHandle property to make a call to the DbiGetDirectory BDE API function. Because it uses a BDE API function directly, you must add "#include <bde.hpp>" in the implementation section of the unit.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

String Directory;

Directory.SetLength(250);

    	char x[250];

    	char y[250];

    	if(DbiGetDirectory(Table1->DBHandle, true, x) != DBIERR_NONE)

    	Application->MessageBox("Error getting current working directory", "Error", MB_OK);

    	else

    	Application->MessageBox(x, "Directory", MB_OK);

    	if (DbiGetDirectory(Table1->DBHandle, false, y) != DBIERR_NONE)

    	Application->MessageBox("Error getting current working directory", "Error", MB_OK);

else

    	Application->MessageBox(y, "Directory", MB_OK);

}


TDataSet::Eof example

This example uses TDataSource's OnDataChange event to detect when the user moves to another record. If the end of file is reached (Eof property becomes true), a message is displayed on the form's status bar.

void __fastcall TForm1::DataSource1DataChange(TObject *Sender, TField *Field)

{

StatusBar1->SimplePanel = true;	//So we can see the status bar

if(Table1->Eof)

    	StatusBar1->SimpleText = "You're already at the end of the table";

}


TDataSet::FieldCount example

This example displays a message box with the names of all fields in the table.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

String Info("The fields are: ");

    	for(int i = 0; i < Table1->FieldCount; i++)

    	Info = Info + Table1->Fields[i]->FieldName + ", ";

    	ShowMessage(Info);

}


TDataSet::Fields example

This example displays a list box listing the names of all the field objects in a TTable.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

for(int i = 0; i < Table1->FieldCount; i++)

ListBox1->Items->Add(Table1->Fields[i]->FieldName);

}


TDBDataSet::UpdateMode example

Consider a COUNTRY table with columns for NAME (the key), CAPITAL, and CONTINENT. Suppose you and another user simultaneously retrieve a record with the following values:

NAME = "Philippines"

CAPITAL = "Nairobi"

CONTINENT = "Africa"

Both you and the other user notice that the information in this record is incorrect and should be changed. Now, suppose the other user changes CONTINENT to "Asia", CAPITAL to "Manila", and posts the change to the database. A few seconds later, you change NAME to "Kenya" and post your change to the database.

If your application has UpdateMode set to WhereKey on the dataset, C++Builder compares the original value of the key column (NAME = "Philippines") to the current value in the database. Since the other user did not change NAME, your update occurs. You think the record is now ["Kenya", "Nairobi", "Africa"] and the other users thinks it is ["Philippines", "Manila", "Asia"]. Unfortunately, it is actually ["Kenya", "Manila", "Asia"], which is still incorrect, even though both you and the other user think you have corrected the mistake. This problem occurred because you had UpdateMode set to its least restrictive level, which does not protect against such occurrences.

If your application had UpdateMode set to WhereAll, the Delphi would check all the columns when you attempt to make your update. Since the other user changed CAPITAL and CONTINENT, Delphi would not let you make the update. When you retrieved the record again, you would see the new values entered by the other user and realize that the mistake had already been corrected.


TBDEDataSet::UpdatesPending example

void __fastcall TForm1::ApplyClick(TObject *Sender)

{

if(Query1->UpdatesPending)

{

    	Database1->StartTransaction();

      	try

        	{

        	Query1->ApplyUpdates(); //try to write 	the updates 	//to the database

        	Database1->Commit(); //on success, commit the changes

        	}

catch(...)

        	{

        	Database1->Rollback(); //on failure, undo any changes

        	throw; //throw the exception again to prevent a call 	//to CommitUpdates()

        	}

      	Query1->CommitUpdates(); //on success, clear the internal 	//cache

    	}

}


TDdeClientConv::ExecuteMacroLines example

The following code executes the macro that exists in the Linew of Memo1.  Wait is a boolean variable that specifies whether to wait for the server to complete macro processing before sending more data to the server.

DdeClientConv1->ExecuteMacroLines(Memo1->Lines, wait);


TDrawGrid::CellRect example

This example uses a string grid, four labels, and a button on a form. When the user clicks the button, the coordinates of the cell in the second column and first row appear in the label captions.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TRect Rectangle = StringGrid1->CellRect(3, 2);

  Label1->Caption = AnsiString(Rectangle.Top) + " is the top";

  Label2->Caption = AnsiString(Rectangle.Bottom) + " is the bottom";

  Label3->Caption = AnsiString(Rectangle.Left) + " is the left side";

  Label4->Caption = AnsiString(Rectangle.Right) + " is the right side";

}


TDrawGrid::MouseToCell example

This example uses a string grid on a form. When the user selects a cell in the grid and releases the mouse button, the column and row coordinates for the cell appear in the cell. The code for displaying the coordinates is written in the OnMouseUp event handler:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  StringGrid1->DefaultColWidth = 100;

}

//---------------------------------------------------------------------------

void __fastcall TForm1::StringGrid1MouseUp(TObject *Sender, TMouseButton Button,

        TShiftState Shift, int X, int Y)

{

  long Column, Row;

  StringGrid1->MouseToCell(X, Y, Column, Row);

  StringGrid1->Cells[Column][Row] = "Col " + AnsiString((int)Column) +

                                    ",Row " + AnsiString((int) Row);

}


TDataSet::Bof example

This example calls TTable's First method to move to the first row.  It then checks that the Bof has been reached and displays a message.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

Table1->First();

if(Table1->Bof)

    	ShowMessage("You're at the beginning of the table");

}


TDBDataSet::Database example

This examples inserts a blank record into a table when the user clicks the button.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

//Make sure that a transaction is not already in progress.

if(!Table1->Database->InTransaction)

{

    	Table1->Database->StartTransaction();

    	Table1->Insert();	//insert a blank row

    	Table1->Database->Commit();

    	}

}


TDataSet::FindField example

void __fastcall TForm1::Button1Click(TObject *Sender)

{

//Put the DataSource into Edit mode, otherwise we won't

    	// be able to change the data

DataSource1->Edit();

  	// This is the safe way to change 'CustNo' field

    	Table1->FindField("CustNo")->AsString = "1234";

//This is *not* the safe way to change 'CustNo' field

    	Table1->Fields[0]->AsString = "1234";

}


TObject::Free example

The following code creates List1 and Object1, then adds Object1 to List1. If the first item in the List property List1 differs from the first item of the Items property of List1 (which shouldn't happen), a message is displayed.

TList * List1;

  	TObject * Object1;

  	List1 = new TList();

try

  	{

  	Object1 = new TObject();

    	try

    	{

    	List1->Add(Object1);

      	if(*List1->List[0] != List1->Items[0])

        	ShowMessage("Something is wrong here");

    	}

    	catch(...)

{

    	Object1->Free();

    	}

  	}

  	catch(...)

  	{

  	List1->Free();

  	}


TDataSet::FreeBookmark example

This example Sets up and saves a bookmark when the user clicks the first button.  It returns to the bookmark when the user clicks the second button.

TBookmark MyBookmark;

//---------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//---------------------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

    // Save the current record position in MyBookmark

  	MyBookmark = Table1->GetBookmark();

  	//...  Other code here

}

//---------------------------------------------------------------------

void __fastcall TForm1::Button2Click(TObject *Sender)

{

// Return to the record associated with MyBookmark

Table1->GotoBookmark(MyBookmark);

//Release the resources for MyBookmark

  	Table1->FreeBookmark(MyBookmark);

}


TDataSet::GetBookmark example

This example Sets up and saves a bookmark when the user clicks the first button.  It returns to the bookmark when the user clicks the second button.

TBookmark MyBookmark;

//---------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//---------------------------------------------------------------------

void __fastcall TForm1::Button1Click(TObject *Sender)

{

    // Save the current record position in MyBookmark

  	MyBookmark = Table1->GetBookmark();

  	//...  Other code here

}

//---------------------------------------------------------------------

void __fastcall TForm1::Button2Click(TObject *Sender)

{

// Return to the record associated with MyBookmark

Table1->GotoBookmark(MyBookmark);

//Release the resources for MyBookmark

  	Table1->FreeBookmark(MyBookmark);

}


SaveInitProc variable

Stores the old value of System::Init when a TComModule object is created. (The new value of System::Init is passed as a parameter to the TComModule constructor.)

extern void* SaveInitProc;

Header

atlvcl.h


AutomationTerminateProc function

Returns true if the automation server can be terminated; returns false otherwise. AutomationTerminateProc always returns true for servers that are not launched with the /automation switch. Otherwise, AutomationTerminateProc returns a value corresponding to the result of a prompt to terminate the server.

bool __fastcall AutomationTerminateProc();

Header

atlvcl.h


SaveVCLComponentToStream function

Saves a VCL component to a stream.

void __fastcall SaveVCLComponentToStream(TComponent *instance, LPSTREAM pStream);

Header

atlvcl.h


LoadVCLComponentFromStream function

Loads a VCL component from a stream.

void __fastcall LoadVCLComponentFromStream(TComponent *instance, LPSTREAM pStream);

Header

atlvcl.h


CreateReflectorWindow function

Creates a window for reflecting messages to an ActiveX control.

TWinControl* CreateReflectorWindow(HWND parent, Controls::TControl* Control);

Header

atlvcl.h


dwDefaultControlMiscFlags const

Specifies miscellaneous OLE flags. dwDefaultControlMiscFlags is passed as a parameter to the DECLARE_OLEMISC_FLAGS macro in the TVclControlImpl definition. dwDefaultControlMiscFlags is also passed as the MiscFlags parameter to the TAxControlRegistrar constructor.

const DWORD dwDefaultControlMiscFlags = OLEMISC_RECOMPOSEONRESIZE | OLEMISC_CANTLINKINSIDE | OLEMISC_INSIDEOUT | OLEMISC_ACTIVATEWHENVISIBLE | OLEMISC_SETCLIENTSITEFIRST;

Header

atlvcl.h


_Module variable

Contains a reference to a TComModule object. _Module is used in many OLE-related methods and functions.

extern TComModule &_Module;

Header

atlvcl.h


DECLARE_OLEMISC_FLAGS macro

Declares miscellaneous OLE flags.

DECLARE_OLEMISC_FLAGS(flags)

Header

atlvcl.h


BEGIN_VERB_MAP, VERB_ENTRY, VERB_ENTRY_EX, END_VERB_MAP macros
BEGIN_VERB_MAP, VERB_ENTRY, VERB_ENTRY_EX, and END_VERB_MAP macros

Declares OLEVERBs for an object.

BEGIN_VERB_MAP()

[VERB_ENTRY(verbId, verbString)]

[VERB_ENTRY_EX(verbId, verbString, mfFlags, verbAttrib)]

END_VERB_MAP()

Header

atlvcl.h


VCL_CONTROL_COM_INTERFACE_ENTRIES macro

Encapsulates the interface entries that are required for exposing a VCL component as an ActiveX control.

This macro is used in code generated by the ActiveX and ActiveForm wizards to define the minimum number of required interfaces.

The macro is used between the BEGIN_COM_MAP and END_COM_MAP macros.

For information about the BEGIN_COM_MAP and END_COM_MAP macros, refer to header files in the CBuilder3\Include\Atl directory and third party documentation for the Microsoft Active Template Library (ATL).

VCL_CONTROL_COM_INTERFACE_ENTRIES(intf)

intf is the name of the dispatch interface for the ActiveX control.

Header

atlvcl.h


VCLCONTROL_IMPL macro

Encapsulates the base classes from which an ActiveX control is derived.

This macro is used in code generated by the ActiveX wizards to define the base classes for an ActiveX control.

VCLCONTROL_IMPL(cppClass, CoClass, VclClass, intf, EventID)

cppClass is the name of the ActiveX control class that is being defined.

CoClass is the name of the ActiveX control's CoClass.

VclClass is the name of the VCL control upon which the ActiveX control is based.

intf is the ActiveX control's dispatch interface.

EventID is the identifier for the ActiveX control's events interface.

Header

atlvcl.h


AUTOOBJECT_COM_INTERFACE_ENTRIES macro

Encapsulates the interfaces required for an automation object.

This macro is used in code generated by the ActiveX wizards.

AUTOOBJECT_COM_INTERFACE_ENTRIES(intf)

intf is the name of the interface from which the ActiveX control is derived.

Header

atlvcl.h


BEGIN_AUTOOBJECT_COM_MAP, END_AUTOOBJECT_COM_MAP macros

This macro is used in code generated by the ActiveX wizards.

BEGIN_AUTOOBJECT_COM_MAP(coclass, intf)

[COM map entries]

END_AUTOOBJECT_COM_MAP

Header

atlvcl.h


PROPERTYPAGE_COM_INTERFACE_ENTRIES macro
PROPERTYPAGE_COM_INTERFACE_ENTRIES

Encapsulates interfaces required for property pages.

This macro is used in code generated by the Property Page wizard.

PROPERTYPAGE_COM_INTERFACE_ENTRIES

Header

atlvcl.h


BEGIN_PROPERTYPAGE_COM_MAP, END_PROPERTYPAGE_COM_MAP macros

This macro is used in code generated by the ActiveX wizards.

BEGIN_PROPERTYPAGE_COM_MAP(coclass)

[Property page COM map entries]

END_PROPERTYPAGE_COM_MAP

Header

atlvcl.h


AUTOOBJECT_IMPL macro

Encapsulates the base classes from which an automation object is derived.

This macro is used in code generated by the ActiveX wizards to define the automation object class.

AUTOOBJECT_IMPL(cppClass, CoClass, intf)

Header

atlvcl.h


REMOTEDATAMODULE_IMPL macro

This macro is used in code generated by the ActiveX wizards.

REMOTEDATAMODULE_IMPL(cppClass, CoClass, VclClass, intf)

Header

atlvcl.h


DUALINTERFACE_IMPL macro

This macro is used in code generated by the ActiveX wizards.

DUALINTERFACE_IMPL(coclass, intf)

Header

atlvcl.h


DUALINTERFACE_ENTRY macro

This macro is used in code generated by the ActiveX wizards.

DUALINTERFACE_ENTRY(i)

Header

atlvcl.h


PROPERTYPAGE_IMPL macro
PROPERTYPAGE_IMPL

This macro is used in code generated by the ActiveX wizards.

PROPERTYPAGE_IMPL(cppClass, CoClass, VclClass)

Header

atlvcl.h


UPDATE_REGISTRY_METHOD macro
UPDATE_REGISTRY_METHOD

This macro is used in code generated by the ActiveX wizards.

UPDATE_REGISTRY_METHOD(code)

Header

atlvcl.h


DECLARE_COMSERVER_REGISTRY macro

See also

This macro is used in code generated by the ActiveX wizards to declare a TComServerRegistrar object, which registers basic information about the COM server.

DECLARE_COMSERVER_REGISTRY(progid, desc)

Header

atlvcl.h


DECLARE_TYPED_COMSERVER_REGISTRY macro
DECLARE_TYPED_COMSERVER_REGISTRY

See also

This macro is used in code generated by the ActiveX wizards to declare a TTypedComServerRegistrar object, which registers basic information about the Automation object.

DECLARE_TYPED_COMSERVER_REGISTRY(progid)

progid is the data module's ProgId.

Header

atlvcl.h


DECLARE_REMOTEDATAMODULE_REGISTRY macro
DECLARE_REMOTEDATAMODULE_REGISTRY

See also

This macro is used in code generated by the ActiveX wizards to declare a TRemoteDataModuleRegistrar object, which registers basic information about the automation object.

DECLARE_REMOTEDATAMODULE_REGISTRY(progid)

progid is the data module's ProgId.

Header

atlvcl.h


DECLARE_ACTIVEXCONTROL_REGISTRY macro
DECLARE_ACTIVEXCONTROL_REGISTRY

See also

This macro is used in code generated by the ActiveX wizards to declare a TAxControlRegistrar object, which registers basic information about the ActiveX control.

DECLARE_ACTIVEXCONTROL_REGISTRY(progid, idbmp)

progid is the ActiveX control's ProgId.

idbmp is the ActiveX control's ToolboxBitmap ID.

Header

atlvcl.h


TAxControlRegistrar

Hierarchy	Properties	Methods	See also

Registers or unregisters an ActiveX control.

Header

atlvcl.h

Description

Typically an instance of this class is created with the DECLARE_ACTIVEXCONTROL_REGISTRY macro.


TAxControlRegistrar properties

TAxControlRegistrar	Alphabetically	Legend

In TAxControlRegistrar

m_BitmapID

m_MiscFlags

m_Verbs

Derived from TComServerRegistrar

m_ClassID

m_ClassKey

m_Description

m_ModuleName

m_ProgID

m_ServerType


TAxControlRegistrar properties

TAxControlRegistrar	By object	Legend

m_BitmapID

m_ClassID

m_ClassKey

m_Description

m_MiscFlags

m_ModuleName

m_ProgID

m_ServerType

m_Verbs


TAxControlRegistrar::m_BitmapID

TAxControlRegistrar

Contains the index of a ToolboxBitmap32 resoure.

int m_BitmapID;


TAxControlRegistrar::m_MiscFlags

TAxControlRegistrar	See also

Contains miscellaneous information about the control.

DWORD m_MiscFlags;

Description

When the TAxControlRegistrar object is created, m_MiscFlags is initialized to the dwDefaultControlMiscFlags constant.


TAxControlRegistrar::m_Verbs

TAxControlRegistrar

Contains the OLE verbs supported by the control.

const OLEVERB* m_Verbs;l


TAxControlRegistrar methods

TAxControlRegistrar	Alphabetically	Legend

In TAxControlRegistrar

TAxControlRegistrar

UpdateRegistry

Derived from TComServerRegistrar

CreateRegKey

DeleteRegKey

Init

NukeRegKey


TAxControlRegistrar methods

TAxControlRegistrar	By object	Legend

CreateRegKey

DeleteRegKey

Init

NukeRegKey

TAxControlRegistrar

UpdateRegistry


TAxControlRegistrar::TAxControlRegistrar

TAxControlRegistrar

Creates a TAxControlRegistrar object.

TAxControlRegistrar(): m_BitmapID(0), m_MiscFlags(dwDefaultControlMiscFlags), m_Verbs(0) {}

TAxControlRegistrar(const CLSID& clsid, AnsiString ProgID, int BitmapID, DWORD MiscFlags = dwDefaultControlMiscFlags, const OLEVERB *verbs = 0) : m_BitmapID(BitmapID), m_MiscFlags(MiscFlags), m_Verbs(verbs), TTypedComServerRegistrar(clsid, ProgID) {}

Description

Initializes data members as shown in the syntax.

Do not call TAxControlRegistrar directly; instead, use the new keyword on the object, which causes TAxControlRegistrar method to be invoked automatically.


TAxControlRegistrar::UpdateRegistry

TAxControlRegistrar

Registers the control, including its type library, using the data contained in the TAxControlRegistrar object; or unregisters the control.

virtual HRESULT UpdateRegistry(bool Register);

Description

Register specifies whether to register or unregister the COM server.


Scope

Protected


Scope

Protected


Hierarchy

TComServerRegistrar


TComModule

Properties	Methods

Extends CComModule to allow it to work in-process and out-of-process and within VCL applications.

For information about the CComModule object, refer to header files in the CBuilder3\Include\Atl directory and third party documentation for the Microsoft Active Template Library (ATL).

Header

atlvcl.h


TComModule properties

TComModule	Alphabetically

In TComModule

m_bAutomationServer

m_bExe

m_bRun

m_InitOle

m_InitProc

m_ThreadID


TComModule properties

TComModule	By object

m_bAutomationServer

m_bExe

m_bRun

m_InitOle

m_InitProc

m_ThreadID


TComModule::m_bAutomationServer

TComModule	See also

Specifies whether the module is an automation server.

bool m_bAutomationServer;

Description

Used in the TComServerRegistrar::UpdateRegistry method to determine whether the module is an Automation server.


TComModule::m_InitOle

TComModule	See also

Contains data for initializing OLE.

TInitOle m_InitOle;

Description

m_InitOle is used in the TComModule constructor to confirm that OLE is initialized properly.


TComModule::m_ThreadID

TComModule	See also

The module’s thread identifier.

DWORD m_ThreadID;

Description

The thread identifier is used in the Unlock method to determine where to post the WM_QUIT message.


TComModule::m_bRun

TComModule	See also

Specifies whether the server is run.

bool m_bRun;

Description

m_bRun is used in the ~TComModule method to determine whether the memory for certain objects needs to be freed.


TComModule::m_bExe

TComModule	See also

Specifies whether the module is a local (EXE) or in-process (DLL) server.

bool m_bExe;

Description

m_bExe is used in the Unlock, TComServerRegistrar::Init, and TComServerRegistrar::UpdateRegistry methods, which must determine whether the module is a local or in-process server.


TComModule::m_InitProc

TComModule	See also

Contains VCL’s initialization procedure.

TProcedure m_InitProc;

Description

m_InitProc is set equal to InitProcedure, which is passed as a parameter of the TComModule constructor. It is assigned to System::InitProc. The old value of System::InitProc is stored in the SaveInitProc variable.


TComModule methods

TComModule	Alphabetically

In TComModule

~TComModule

DoFileAndObjectRegistration

TComModule

Unlock


TComModule methods

TComModule	By object

~TComModule

DoFileAndObjectRegistration

TComModule

Unlock


TComModule::~TComModule

TComModule	See also

Frees the memory associated with the TComModule object. Do not call ~TComModule directly; instead, use the delete keyword on the object, which causes ~TComModule to be invoked automatically.

~TComModule(void)


TComModule::TComModule

TComModule	See also

Creates a new TComModule object.

TComModule(): m_ThreadID(0), m_bRun(true), m_bExe(false), m_InitProc(0), m_bAutomationServer(false) {}

TComModule(TProcedure InitProcedure): m_ThreadID(0), m_bRun(true), m_bExe(true), m_InitProc(InitProcedure), m_bAutomationServer(false);

Description

Initializes data members as shown in the function prototype. If InitProcedure is specified, TComModule performs the following tasks:

•	Confirms that OLE is initialized properly.

•	Sets the SaveInitProc variable to System::InitProc (if m_bExe and m_InitProc are true).

•	Sets System::InitProc to InitProcedure (if m_bExe and m_InitProc are true).


TComModule::DoFileAndObjectRegistration

TComModule

Registers the server according to its command-line switches and instancing settings.

void DoFileAndObjectRegistration()

Description

Registers the server according to the /automation, /embedding, /regserver, and /unregserver command-line switches. Also registers the server for single or multiple use.


TComModule::Unlock

TComModule	See also

Posts a WM_QUIT message if the module represents a local server.

LONG TComModule::Unlock();

Description

Calls CComModule::Unlock. If CComModule::Unlock returns 0 and m_bExe is true, Unlock posts a WM_QUIT message to the thread specified by the m_ThreadID data member.


TComServerRegistrar

Properties	Methods	See also

Registers or unregisters a COM server, not including its type library.

Header

atlvcl.h

Description

Typically an instance of this class is created with the DECLARE_COMSERVER_REGISTRY macro.


TComServerRegistrar properties

TComServerRegistrar	Alphabetically	Legend

In TComServerRegistrar

m_ClassID

m_ClassKey

m_Description

m_ModuleName

m_ProgID

m_ServerType


TComServerRegistrar properties

TComServerRegistrar	By object	Legend

m_ClassID

m_ClassKey

m_Description

m_ModuleName

m_ProgID

m_ServerType


TComServerRegistrar::m_ProgID

TComServerRegistrar

Contains the COM server’s ProgID.

AnsiString m_ProgID;


TComServerRegistrar::m_ClassKey

TComServerRegistrar	See also

Contains the COM server’s ClassKey.

CLSID m_ClassID;

Description

m_ClassKey is initialized automatically when the TComServerRegistrar object is created. m_ClassKey can be reinitialized with the Init method.


TComServerRegistrar::m_Description

TComServerRegistrar

Contains the COM server’s description.

AnsiString m_Description;


TComServerRegistrar::m_ServerType

TComServerRegistrar	See also

Contains the COM server’s type.

AnsiString m_ServerType;

Description

m_ServerType is initialized automatically when the TComServerRegistrar object is created. m_ServerType can be reinitialized with the Init method.


TComServerRegistrar::m_ModuleName

TComServerRegistrar	See also

Contains the COM server’s module name.

WideString m_ModuleName;

Description

m_ModuleName is initialized automatically when the TComServerRegistrar object is created. m_ModuleName can be reinitialized with the Init method.


TComServerRegistrar::m_ClassID

TComServerRegistrar

Contains the COM server’s ClassID.

CLSID m_ClassID;


TComServerRegistrar methods

TComServerRegistrar	Alphabetically	Legend

In TComServerRegistrar

~TComServerRegistrar

CreateRegKey

DeleteRegKey

Init

NukeRegKey

TComServerRegistrar

UpdateRegistry


TComServerRegistrar methods

TComServerRegistrar	By object	Legend

~TComServerRegistrar

CreateRegKey

DeleteRegKey

Init

NukeRegKey

TComServerRegistrar

UpdateRegistry


TComServerRegistrar::TComServerRegistrar

TComServerRegistrar	See also

Creates a TComServerRegistrar object.

TComServerRegistrar(const CLSID& clsid, AnsiString progID, AnsiString description) : m_ClassID(clsid), m_ProgID(progID), m_Description(description) { Init(); }

Description

Do not call TComServerRegistrar directly; instead, use the new keyword on the object, which causes TComServerRegistrar method to be invoked automatically.

TComServerRegistrar calls the Init method.


TComServerRegistrar::~TComServerRegistrar

TComServerRegistrar	See also

Frees the memory associated with the TComServerRegistrar object.

~TComServerRegistrar() {}

Description

Do not call ~TComServerRegistrar directly; instead, use the delete keyword on the object, which causes ~TComServerRegistrar method to be invoked automatically.


TComServerRegistrar::CreateRegKey

TComServerRegistrar	See also

Creates a registry key.

static void  CreateRegKey(AnsiString Key, AnsiString ValueName, AnsiString Value);

Description

Key is the name of the key under which to add a new value.

ValueName is the name to associate with the new value.

Value is the new value.


TComServerRegistrar::DeleteRegKey

TComServerRegistrar	See also

Deletes a registry key.

static void  DeleteRegKey(AnsiString Key);

Description

Key is the name of the key to delete.

Under Windows 95, DeleteRegKey also deletes subkeys. Under Windows NT, DeleteRegKey only works on keys without subkeys.


TComServerRegistrar::NukeRegKey

TComServerRegistrar	See also

Deletes a registry key and its subkeys

static void  NukeRegKey(AnsiString Key);

Description

Key is the name of the key to delete. The subkeys of Key are also deleted.


TComServerRegistrar::Init

TComServerRegistrar	See also

Initializes data associated with the TComServerRegistrar object.

void Init();

Description

Initializes the m_ModuleName, m_ClassKey, and m_ServerType properties.

Init is called from the TComServerRegistrar method.


TComServerRegistrar::UpdateRegistry

TComServerRegistrar

Registers the COM server using the data contained in the TComServerRegistrar object; or unregisters the COM server.

virtual HRESULT UpdateRegistry(bool Register);

Description

Register specifies whether to register or unregister the COM server.


Scope

Protected


Scope

Protected


IDataBrokerImpl

Properties	Methods	See also

Implements an IDataBroker interface, which publishes datasets residing in a TDataModule object.

Header

atlvcl.h


IDataBrokerImpl properties

IDataBrokerImpl	Alphabetically

In IDataBrokerImpl

m_DataModule


IDataBrokerImpl properties

IDataBrokerImpl	By object

m_DataModule


IDataBrokerImpl::m_DataModule

IDataBrokerImpl	See also

Contains a TDataModule object.

DM* m_DataModule;

Description

The object assigned to m_DataModule is created in the IDataBrokerImpl constructor.


IDataBrokerImpl methods

IDataBrokerImpl	Alphabetically

In IDataBrokerImpl

~IDataBrokerImpl

GetProviderNames

IDataBrokerImpl


IDataBrokerImpl methods

IDataBrokerImpl	By object

~IDataBrokerImpl

GetProviderNames

IDataBrokerImpl


IDataBrokerImpl::~IDataBrokerImpl

IDataBrokerImpl	See also

~IDataBrokerImpl frees the memory associated with the IDataBrokerImpl object. Do not call ~IDataBrokerImpl directly; instead, use the delete keyword on the object, which causes ~IDataBrokerImpl to be invoked automatically.

~IDataBrokerImpl();

Description

~IDataBrokerImpl calls the Bdeprov::UseBdeProv function and frees the memory associated with the m_DataModule property.


IDataBrokerImpl::IDataBrokerImpl

IDataBrokerImpl	See also

Creates an IDataBrokerImpl object.

IDataBrokerImpl();

Description

Creates a TDataModule object, assigning it to the m_DataModule property.


IDataBrokerImpl::GetProviderNames

IDataBrokerImpl

Stores the names of m_DataModule’s published datasets in Result.

HRESULT STDMETHODCALLTYPE GetProviderNames(System::OleVariant &Result);

Description

On success, GetProviderNames returns S_OK; otherwise, GetProviderNames returns one of the GetTypeInfo return values.


TLicenseString

Methods	See also

A template for an object that verifies whether an ActiveX control is licensed on the current machine.

Header

atlvcl.h

template <class T>

T is the ActiveX control class.

Description

For ActiveX controls that require license verification, the ActiveX wizards generate code for a TLicenseString object, which is passed to the DECLARE_CLASSFACTORY2 macro.

For information about the DECLARE_CLASSFACTORY2 macro, refer to header files in the CBuilder3\Include\Atl directory and third party documentation for the Microsoft Active Template Library (ATL).

The methods of the TLicenseString object simply call the corresponding methods in the ActiveX control class. Use the methods in the ActiveX control class to override the default implementation for the ActiveX control's license verification.


TLicenseString methods

TLicenseString	Alphabetically

In TLicenseString

GetLicenseKey

IsLicenseValid

VerifyLicenseKey


TLicenseString methods

TLicenseString	By object

GetLicenseKey

IsLicenseValid

VerifyLicenseKey


TLicenseString::GetLicenseKey

TLicenseString	See also

Retrieves the ActiveX control’s license key.

static BOOL GetLicenseKey(DWORD /*dwReserved*/, BSTR *pStr)

Description

The DWORD parameter is reserved for future use.

pStr is the object in which the license key is stored.

GetLicenseKey always returns TRUE.


TLicenseString::VerifyLicenseKey

TLicenseString	See also

Compares a string to the ActiveX control’s license key.

static BOOL VerifyLicenseKey(BSTR str);

Description

Returns true if str matches the ActiveX control’s license key; returns false otherwise.


TLicenseString::IsLicenseValid

TLicenseString	See also

Allows the ActiveX control to determine whether its license is valid.

static BOOL IsLicenseValid();

Description

Calls the ActiveX control’s IsLicenseValid method, returning the result.


TRemoteDataModuleRegistrar

Hierarchy	Properties	Methods	See also

Registers or unregisters a remote data module, including its type library.

Header

atlvcl.h

Description

Typically an instance of this class is created with the DECLARE_REMOTEDATAMODULE_REGISTRY macro.


TRemoteDataModuleRegistrar properties

TRemoteDataModuleRegistrar	Alphabetically	Legend

Derived from TComServerRegistrar

m_ClassID

m_ClassKey

m_Description

m_ModuleName

m_ProgID

m_ServerType


TRemoteDataModuleRegistrar properties

TRemoteDataModuleRegistrar	By object	Legend

m_ClassID

m_ClassKey

m_Description

m_ModuleName

m_ProgID

m_ServerType


TRemoteDataModuleRegistrar methods

TRemoteDataModuleRegistrar	Alphabetically	Legend

In TRemoteDataModuleRegistrar

TRemoteDataModuleRegistrar

UpdateRegistry

Derived from TComServerRegistrar

CreateRegKey

DeleteRegKey

Init

NukeRegKey


TRemoteDataModuleRegistrar methods

TRemoteDataModuleRegistrar	By object	Legend

CreateRegKey

DeleteRegKey

Init

NukeRegKey

TRemoteDataModuleRegistrar

UpdateRegistry


TRemoteDataModuleRegistrar::TRemoteDataModuleRegistrar

TRemoteDataModuleRegistrar

Creates a TRemoteDataModuleRegistrar object.

TRemoteDataModuleRegistrar() : TTypedComServerRegistrar() {}

TRemoteDataModuleRegistrar(const CLSID& clsid, AnsiString ProgID):

TTypedComServerRegistrar(clsid, ProgID) {}

Description

Do not call TRemoteDataModuleRegistrar directly; instead, use the new keyword on the object, which causes TRemoteDataModuleRegistrar method to be invoked automatically.


TRemoteDataModuleRegistrar::UpdateRegistry

TRemoteDataModuleRegistrar

Registers the COM server, including its type information, using the data contained in the TRemoteDataModuleRegistrar object; or unregisters the COM server.

virtual HRESULT UpdateRegistry(bool Register);


Scope

Protected


Scope

Protected


Hierarchy

TComServerRegistrar


ISimpleFrameSiteImpl

Methods

Implements an ISimpleFrameSite object.

For information about ISimpleFrameSite, refer to third party documentation for the Microsoft Active Template Library (ATL).

Header

atlvcl.h


ISimpleFrameSiteImpl methods

ISimpleFrameSiteImpl	Alphabetically

In ISimpleFrameSiteImpl

PostMessageFilter

PreMessageFilter

QueryInterface


ISimpleFrameSiteImpl methods

ISimpleFrameSiteImpl	By object

PostMessageFilter

PreMessageFilter

QueryInterface


ISimpleFrameSiteImpl::PostMessageFilter

ISimpleFrameSiteImpl

Implements a post-message filter.

STDMETHOD(PostMessageFilter)(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp, LRESULT* plResult, DWORD dwCookie);


ISimpleFrameSiteImpl::PreMessageFilter

ISimpleFrameSiteImpl

Implements a pre-message filter

STDMETHOD(PreMessageFilter)(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp, LRESULT* plResult, DWORD* pdwCookie);


ISimpleFrameSiteImpl::QueryInterface

ISimpleFrameSiteImpl

Implements QueryInterface.

STDMETHOD(QueryInterface)(REFIID riid, void ** ppvObject) = 0;


TTypedComServerRegistrar

Hierarchy	Methods	See also

Registers or unregisters a COM server, including its type library.

Header

atlvcl.h

Description

Typically an instance of this class is created with the DECLARE_TYPED_COMSERVER_REGISTRY macro.


TTypedComServerRegistrar methods

TTypedComServerRegistrar	Alphabetically

In TTypedComServerRegistrar

TTypedComServerRegistrar

UpdateRegistry


TTypedComServerRegistrar methods

TTypedComServerRegistrar	By object

TTypedComServerRegistrar

UpdateRegistry


TTypedComServerRegistrar::TTypedComServerRegistrar

TTypedComServerRegistrar	See also

Creates a TTypedComServerRegistrar object.

TTypedComServerRegistrar(): TComServerRegistrar() {}

TTypedComServerRegistrar(const CLSID& clsid, AnsiString ProgID):TComServerRegistrar(clsid, ProgID, NULL) {}

Description

Do not call TTypedComServerRegistrar directly; instead, use the new keyword on the object, which causes TTypedComServerRegistrar method to be invoked automatically.


TTypedComServerRegistrar::UpdateRegistry

TTypedComServerRegistrar

Registers the COM server, including its type information, using the data contained in the TTypedComServerRegistrar object; or unregisters the COM server.

HRESULT UpdateRegistry(bool Register);

Description

Register specifies whether to register or unregister the COM server.


Hierarchy

TComServerRegistrar


TValidateLicense

Methods

An object that contains one method, IsGUIDInFile, that verifies whether a license string GUID is in a license (.LIC) file.

Header

atlvcl.h

Description

For ActiveX controls that require license verification, the ActiveX control wizard uses TValidateLicense::IsGUIDInFile to provide a default implementation of the ActiveX control's IsLicenseValid method.

For more information about ActiveX control licensing, refer to third party documentation for the Microsoft Active Template Library (ATL).


TValidateLicense methods

TValidateLicense	Alphabetically

In TValidateLicense

IsGUIDInFile


TValidateLicense methods

TValidateLicense	By object

IsGUIDInFile


TValidateLicense::IsGUIDInFile

TValidateLicense

Returns true if the specified GUID is in the specified license file.

static BOOL IsGUIDInFile(const WCHAR *szGUID, const TCHAR *szLicFileName);

Description

szGUID is a GUIDl.

szLicFileName is the name of the license file.

IsGUIDInFile searches for the license file in the following directories, first to last:

•	The directory containing the ActiveX control.

•	The default directory.

•	The container’s directory.

•	The Windows directory.

•	The directories in the system path.


TVclComControl

Hierarchy	Properties	Methods	See also

A template for creating an ActiveX control from a VCL control.

TVclComControl is used in code generated by the ActiveX wizards.

Header

atlvcl.h

template <class T, class TVCL>

Description

T is the ActiveX control that is created.

TVCL is the VCL control from which the ActiveX control is created.


TVclComControl properties

TVclComControl	Alphabetically	Legend

In TVclComControl

m_AmbientDriver

m_hWnd

m_VclCtl

m_VclWinCtl


TVclComControl properties

TVclComControl	By object	Legend

m_AmbientDriver

m_hWnd

m_VclCtl

m_VclWinCtl


TVclComControl::m_hWnd

TVclComControl

Contains the window handle for the ActiveX control.

HWND m_hWnd;


TVclComControl::m_VclWinCtl

TVclComControl	See also

Contains a wrapper for a window that reflects messages to the VCL control.

TWinControlAccess<TWinControl>* m_VclWinCtl;

Description


TVclComControl::m_VclCtl

TVclComControl	See also

Contains a wrapper for the VCL control.

TWinControlAccess<TVCL>* m_VclCtl;

Description


TVclComControl::m_AmbientDriver

TVclComControl

Contains the ambient properties of the container.

TAutoDriver<IDispatch> m_AmbientDriver;

Description

m_AmbientDriver is initialized in the IOleObject_SetClientSite method. m_AmbientDriver is defined in the OnAmbientPropertyChange method.


TVclComControl methods

TVclComControl	Alphabetically	Legend

In TVclComControl

~TVclComControl

ControlQueryInterface

ControlWndProc

Create

CreateControlWindow

FireOnChanged

FireOnRequestEdit

Initialize

InitializeControl

IOleObject_SetClientSite

IPersistStreamInit_Load

IPersistStreamInit_Save

ISimpleFrameSite_PostMessageFilter

ISimpleFrameSite_PreMessageFilter

RecreateWnd

ShowWindow

TVclComControl

WndProc


TVclComControl methods

TVclComControl	By object	Legend

~TVclComControl

ControlQueryInterface

ControlWndProc

CreateControlWindow

Create

FireOnChanged

FireOnRequestEdit

InitializeControl

Initialize

IOleObject_SetClientSite

IPersistStreamInit_Load

IPersistStreamInit_Save

ISimpleFrameSite_PostMessageFilter

ISimpleFrameSite_PreMessageFilter

RecreateWnd

ShowWindow

TVclComControl

WndProc


TVclComControl::TVclComControl

TVclComControl	See also

Creates a TVclComControl object.

TVclComControl(void): m_VclCtl(0), m_VclWinCtl(0), m_hWnd(0), m_CtlWndProc(0), CComControlBase(m_hWnd);

Description

Do not call TVclComControl directly; instead, use the new keyword on the object, which causes the TVclComControl method to be invoked automatically.

TVclComControl calls the Init method.


TVclComControl::~TVclComControl

TVclComControl	See also

Frees the memory associated with the ~TVclComControl object.

~TVclComControl(void);

Description

Do not call ~TVclComControl directly; instead, use the delete keyword on the object, which causes ~TVclComControl to be invoked automatically.


TVclComControl::ControlQueryInterface

TVclComControl

Retrieves a pointer (ppv) to the requested interface (iid).

virtual HRESULT ControlQueryInterface(const IID& iid, void** ppv);

Description

The requested interface must be listed in the COM map table.


TVclComControl::ControlWndProc

TVclComControl	See also

Handles Windows messages to the ActiveX control as if they are ActiveX messages.

virtual void ControlWndProc(Messages::TMessage& Message);

Description

ControlWndProc is called from the WndProc method.


TVclComControl::Create

TVclComControl	See also

Creates a window for the ActiveX control, returning the window handle.

HWND Create(HWND hWndParent, RECT& rcPos);

Description

Create performs the following tasks:

•	Initializes m_VclWinCtl->ParentWindow to hWndParent.

•	Initializes m_VclWinCtl->BoundsRect to rcPos.

•	Initializes m_hWnd to mVclWinCtl->GetWindowHandle().

•	Forces the window to be created and shown.


TVclComControl::InitializeControl

TVclComControl	See also

Virtual function that can be overridden in a derived class so the control can perform more initialization tasks.

virtual void InitializeControl() {}

Description

InitializeControl is called in the Initialize method.


TVclComControl::Initialize

TVclComControl	See also

Initializes the TComControl object.

void Initialize();

Description

Initialize performs the following tasks:

•	Creates a wrapper for the VCL control, storing it in the m_VclCtl property.

•	Creates a wrapper for a message reflector window if necessary, storing it in the m_VclWinCtl property. (Obtains a handle to the reflector window by calling the AxCtrls::ParkingWindow() function.)

•	Sets m_VclCtl->WindowProc to the WndProc method.

•	Calls the InitializeControl method


TVclComControl::CreateControlWindow

TVclComControl	See also

Calls the Create method.

HWND CreateControlWindow(HWND hWndParent, RECT& rcPos);


TVclComControl::FireOnChanged

TVclComControl	See also

Notifies all connected IPropertyNotifySink interfaces that the specified control property has changed.

HRESULT FireOnChanged(DISPID dispID);

Description

Calls CFirePropNotifyEvent::FireOnChanged, returning the result. Returns S_OK if the control is not derived from IPropertyNotifySink.


TVclComControl::FireOnRequestEdit

TVclComControl	See also

Notifies all connected IPropertyNotifySink interfaces that the specified control property is about to change.

HRESULT FireOnRequestEdit(DISPID dispID);

Description

Calls CFirePropNotifyEvent::FireOnRequestEdit, returning the result. eturns S_OK if the control is not derived from IPropertyNotifySink.


TVclComControl::IOleObject_SetClientSite

TVclComControl	See also

Sets the client site for the ActiveX control.

HRESULT IOleObject_SetClientSite(IOleClientSite *pClientSite);

Description

IOleObject_SetClientSite performs the following tasks:

•	Calls CComModule::IOleObject_SetClientSite.

•	Confirms that the ActiveX control is registered properly.

•	Initializes the m_AmbientDriver property.

•	Enables the Ctl3D style.


TVclComControl::IPersistStreamInit_Load

TVclComControl	See also

Loads a VCL component from a stream into the m_VclCtl property.

HRESULT IPersistStreamInit_Load(LPSTREAM pStm, ATL_PROPMAP_ENTRY* pMap);

Description

IPersistStreamInit_Load uses the LoadVCLControlFromStream function.


TVclComControl::IPersistStreamInit_Save

TVclComControl	See also

Saves the VCL component in the m_VclCtl property to a stream.

HRESULT IPersistStreamInit_Save(LPSTREAM pStm, BOOL /* fClearDirty */, ATL_PROPMAP_ENTRY* pMap);

Description

IPersistStreamIni_Save uses the SaveVCLControlToStream function.


TVclComControl::ISimpleFrameSite_PreMessageFilter

TVclComControl	See also

Handles pre-message filtering for a simple frame site.

HRESULT ISimpleFrameSite_PreMessageFilter(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp, LRESULT* plResult, DWORD* pdwCookie)

Description

ISimpleFrameSite_PreMessageFilter is called from ISimpleFrameSite::PreMessageFilter.


TVclComControl::ISimpleFrameSite_PostMessageFilter

TVclComControl	See also

Handles post-message filtering for a simple frame site.

HRESULT ISimpleFrameSite_PostMessageFilter(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp, LRESULT* plResult, DWORD dwCookie);

Description

SimpleFrameSite_PostMessageFilter is called from ISimpleFrameSite::PostMessageFilter.


TVclComControl::RecreateWnd

TVclComControl	See also

Recreates the window for the ActiveX control.

void RecreateWnd();


TVclComControl::ShowWindow

TVclComControl

Sets the window’s show state.

BOOL ShowWindow(int nCmdShow);

Description

For information about the nCmdShow, see ::ShowWindow in the Win32 Reference.


TVclComControl::WndProc

TVclComControl	See also

Handles Windows messages to the ActiveX control.

virtual void __fastcall WndProc(Messages::TMessage& Message);

Description

Forwards the messages to the ControlWndProc method.


Scope

Protected


Scope

Protected


Hierarchy

CComControlBase


TVclControlImpl

Hierarchy	Methods	See also

A template for an ActiveX control that is based on a VCL control.

TVclControlImpl is used in code generated by the ActiveX wizards.

Header

atlvcl.h

template <class T, class TVCL, const CLSID* pclsid, const IID* piid, const IID* peventsid, const GUID* plibid>

Description

T is the ActiveX control that is created.

TVCL is the VCL control upon which the ActiveX control is based.

pclsid is the Class ID of the ActiveX control.

piid is the primary interface for the ActiveX control.

peventsid is the outgoing events interface for the ActiveX control.

plibid is the GUID of the type libary for the ActiveX control.

TVclControlImpl is derived from the following classes:

•	CComObjectRootEx

•	CComCoClass

•	TVclComControl

•	IProvideClassInfo2Impl

•	IPersistStreamInitImpl

•	IPersistStorageImpl

•	IQuickActivateImpl

•	IOleControlImpl

•	IOleObjectImpl

•	IOleInPlaceActiveObjectImpl

•	IViewObjectExImpl

•	IOleInPlaceObjectWindowlessImpl

•	IDataObjectImpl

•	ISpecifyPropertyPagesImpl

•	IConnectionPointContainerImpl

•	ISupportErrorInfo

•	ISimpleFrameSiteImpl


TVclControlImpl methods

TVclControlImpl	Alphabetically

In TVclControlImpl

~TVclControlImpl

FinalConstruct

FinalRelease

GetControllingUnknown

GetViewStatus

InterfaceSupportsErrorInfo

OnAmbientPropertyChange

OnDraw

SetObjectRects

TVclControlImpl

Derived from base classes

For information about methods derived from base classes, see the TVclControlImpl topic.


TVclControlImpl methods

TVclControlImpl	By object

~TVclControlImpl

FinalConstruct

FinalRelease

GetControllingUnknown

GetViewStatus

InterfaceSupportsErrorInfo

OnAmbientPropertyChange

OnDraw

SetObjectRects

TVclControlImpl

Derived from base classes

For information about methods derived from base classes, see the TVclControlImpl topic.


TVclControlImpl::TVclControlImpl

TVclControlImpl	See also

Creates a TVclControlImpl object.

TVclControlImpl() {}

Description

Do not call TVclControlImpl directly; instead, use the new keyword on the object, which causes the TVclControlImpl method to be invoked automatically.


TVclControlImpl::~TVclControlImpl

TVclControlImpl	See also

Frees the memory associated with the ~TVclControlImpl object.

~TVclControlImpl() {}

Description

Do not call ~TVclControlImpl directly; instead, use the delete keyword on the object, which causes ~TVclControlImpl to be invoked automatically.


TVclControlImpl::FinalConstruct

TVclControlImpl	See also

Initializes data associated with the TVclComControlImpl object.

HRESULT FinalConstruct()

Description

TVclControlImpl calls TVclComControl::Initialize, and then returns S_OK.


TVclControlImpl::FinalRelease

TVclControlImpl

Does nothing.

void FinalRelease();


TVclControlImpl::GetControllingUnknown

TVclControlImpl

Returns the ActiveX control’s outer IUnknown interface.

virtual IUnknown* GetControllingUnknown();


TVclControlImpl::GetViewStatus

TVclControlImpl

Retrieves information about the ActiveX controls view.

STDMETHOD(GetViewStatus)(DWORD* pdwStatus);

Description

GetViewStatus sets the value of pdwStatus to VIEWSTATUS_SOLIDBKGND | VIEWSTATUS_OPAQUE, and then returns S_OK.


TVclControlImpl::InterfaceSupportsErrorInfo

TVclControlImpl

Determines whether an interface supports error information.

STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid);

Description

Returns S_OK if the interface supports error information; returns S_FALSE otherwise.


TVclControlImpl::OnAmbientPropertyChange

TVclControlImpl

Changes the ActiveX control’s background color, foreground color, and font properties to match the container’s corresponding properties.

STDMETHOD(OnAmbientPropertyChange)(DISPID dispid);

Description

Changes to the container’s font and foreground color will be ignored unless the ActiveX control’s ParentFont property is true.

Changes to the container’s background color will be ignored unless the ActiveX control’s ParentColor property is true.


TVclControlImpl::OnDraw

TVclControlImpl

Handles the painting of the ActiveX control’s window.

HRESULT OnDraw(ATL_DRAWINFO& di);


TVclControlImpl::SetObjectRects

TVclControlImpl

Sets the position of the ActiveX control’s window.

STDMETHOD(SetObjectRects)(LPCRECT prcPos,LPCRECT prcClip);


Hierarchy

See TVclControlImpl topic.


TVclPropertyPage

Hierarchy	Properties	Methods	See also

A template for an ActiveX property page.

TVclPropertyPage is used in code generated by the PropertyPage wizard.

Header

atlvcl.h

template <class T, const CLSID* pclsid, class ppclass>

Description

T is the property page class.

pclsid is the class id for the property page class.

ppclass is the VCL component class for the property page.


TVclPropertyPage properties

TVclPropertyPage	Alphabetically

In TVclPropertyPage

m_InnerUnk

m_PPImpl


TVclPropertyPage properties

TVclPropertyPage	By object

m_InnerUnk

m_PPImpl


TVclPropertyPage::m_PPImpl

TVclPropertyPage	See also

Contains the property page implementation.

TPropertyPageImpl* m_PPImpl;

Description

m_PPImpl is created and initialized by the FinalConstruct method. The interface for m_PPImpl is contained in the m_InnerUnk property.


TVclPropertyPage::m_InnerUnk

TVclPropertyPage	See also

Contains an interface to the property page implementation.

IUnknown* m_InnerUnk;

Description

m_InnerUnk is initialized by the FinalConstruct method. The property page implementation is contained in the m_PPImpl property.


TVclPropertyPage methods

TVclPropertyPage	Alphabetically

In TVclPropertyPage

~TVclPropertyPage

FinalConstruct

FinalRelease

TVclPropertyPage


TVclPropertyPage methods

TVclPropertyPage	By object

~TVclPropertyPage

FinalConstruct

FinalRelease

TVclPropertyPage


TVclPropertyPage::~TVclPropertyPage

TVclPropertyPage	See also

Frees the memory associated with the TVclPropertyPage object.

~TVCLPropertyPage() {}

Description

Do not call ~TVclPropertyPage directly; instead, use the delete keyword on the object, which causes ~TVclPropertyPage method to be invoked automatically.


TVclPropertyPage::TVclPropertyPage

TVclPropertyPage	See also

Creates a TVclPropertyPage object.

TVCLPropertyPage(void): m_PPImpl(0), m_InnerUnk(0) {}

Description

Do not call TVclPropertyPage directly; instead, use the new keyword on the object, which causes TVclPropertyPage method to be invoked automatically.


TVclPropertyPage::FinalConstruct

TVclPropertyPage	See also

Initializes data associated with the TVclPropertyPage object.

HRESULT FinalConstruct(void);

Description

Initializes the m_PPImpl and m_InnerUnk properties.


TVclPropertyPage::FinalRelease

TVclPropertyPage	See also

Frees the memory associated with the TVclPropertyPage object.

void FinalRelease(void)

Description

Frees the memory associated with the m_PPImpl and m_InnerUnk properties. Calls the FinaleRelease method of the base class.


Hierarchy

CComObjectRootEx

IUnknown


TVclPtr

Methods	See also

A template for a smart pointer. A smart pointer encapsulates a standard pointer, handling its memory management. For example, when a smart pointer is deleted, such as when it goes out of scope, the memory associated with the pointer is freed.

Header

atlvcl.h

Description

TVclPtr is used in the SaveVCLComponentToStream and LoadVCLComponentFromStream functions.


TVclPtr methods

TVclPtr	Alphabetically

In TVclPtr

~TVclPtr

get

operator->

operator!

operator!=

operator&

operator*

operator=

operator==

operatorT*

release

reset

TVclPtr


TVclPtr methods

TVclPtr	By object

~TVclPtr

get

operator!=

operator!

operator&

operator*

operator==

operator=

operator->

operatorT*

release

reset

TVclPtr


TVclPtr::get

TVclPtr	See also

Returns the encapsulated pointer.

T* get() const { return m_ptr;    }


TVclPtr::release

TVclPtr	See also

Releases the encapsulated pointer.

T* release() { return reset(0); }


TVclPtr::reset

TVclPtr	See also

Resets the encapsulated pointer.

T* reset(T* p = 0) { T* tmp = m_ptr; m_ptr = p; return tmp; }


TVclPtr::TVclPtr

TVclPtr	See also

Creates a new TVclPtr object.

TVclPtr(T* p = 0) : m_ptr(p) {}

TVclPtr(TVclPtr<T>& src) : m_ptr(src.release())  {}

TVclPtr& operator= (TVclPtr<T>& rhs) { reset(rhs.release()); return *this; }


TVclPtr::~TVclPtr

TVclPtr	See also

Frees the memory associated with the TVclPtr object. Do not call ~TVclPtr directly. Instead, use the delete keyword on the object, which causes ~TVclPtr to be invoked automatically.

~TVclPtr() { delete m_ptr; }


TVclPtr::operatorT*

TVclPtr

Implements the T-asterisk (T*) operator, where T is the class name for the TVclPtr object.

operator T* () const { return m_ptr;}


TVclPtr::operator=

TVclPtr

Implements the equal (=) operator.

TVclPtr& operator= (TVclPtr<T>& rhs) { reset(rhs.release()); return *this; }


TVclPtr::operator->

TVclPtr

Implements the right arrow (->) operator.

T* operator->() const { _ASSERTE(m_ptr); return m_ptr;  }


TVclPtr::operator&

TVclPtr

Implements the ampersand (&) operator.

T**  operator &()/*const*/ { return &m_ptr; }


TVclPtr::operator*

TVclPtr

Implements the asterisk (*) operator.

T& operator *  () const    { _ASSERTE(m_ptr); return *m_ptr; }


TVclPtr::operator!

TVclPtr

Implements the exclamation point (!) operator.

bool operator !() const    { return m_ptr == 0; }


TVclPtr::operator==

TVclPtr

Implements the double-equal (==) operator.

bool operator == (T* rhs)            const     { return m_ptr == rhs;}

bool operator == (const TVclPtr<T>& rhs) const { return m_ptr == rhs.m_ptr; }


TVclPtr::operator!=

TVclPtr

Implements the exclamation point-equal (!=) operator.

bool operator != (T* rhs)            const     { return m_ptr != rhs;}

bool operator != (const TVclPtr<T>& rhs) const { return m_ptr != rhs.m_ptr; }


TWinControlAccess

Methods

Template for a class that wraps the window handle of an ActiveX control.

TWinControlAccess is used in code generated by the ActiveX control wizards.

Header

atlvcl.h

template <class T>

Description

T is the wrapper class that is created.


TWinControlAccess methods

TWinControlAccess	Alphabetically

In TWinControlAccess

DoDestroyHandle

GetWindowHandle

TWinControlAccess


TWinControlAccess methods

TWinControlAccess	By object

DoDestroyHandle

GetWindowHandle

TWinControlAccess


TWinControlAccess::TWinControlAccess

TWinControlAccess

Creates a TWinControlAccess object.

__fastcall virtual TWinControlAccess(Classes::TComponent* AOwner): T(AOwner) {}

__fastcall TWinControlAccess(HWND ParentWindow): T(ParentWindow) {}

Description

AOwner is the owner of the ActiveX control.

ParentWindow is the handle ActiveX control’s parent window.

Do not call TWinControlAccess directly; instead, use the new keyword on the object, which causes TWinControlAccess method to be invoked automatically.


TWinControlAccess::DoDestroyHandle

TWinControlAccess

Calls the window’s DestroyHandle method.

void DoDestroyHandle(void) {DestroyHandle();}


TWinControlAccess::GetWindowHandle

TWinControlAccess

Returns the window’s WindowHandle property.

HWND GetWindowHandle(void) {return WindowHandle;}